Skip to content
Skills Library
Management & product · Planning

forge-shape

/forge-shape

Shape a vague idea into a clear plan through codebase investigation and convergent one-at-a-time questioning. Use when the user has a rough idea or problem that needs specifying before issue creation.

Repository
forge ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Shape a vague idea into a clear plan through codebase investigation and convergent one-at-a-time questioning. Use when the user has a rough idea or problem that needs specifying before issue creation.

Original author description

Shape a vague idea into a clear plan through codebase investigation and convergent one-at-a-time questioning. Use when the user has a rough idea or problem that needs specifying before issue creation.

How it works

  1. Input
  2. Process
  3. Output Format
  4. Guidelines
  5. Related Skills
  6. Example Usage
Original SKILL.md headings · 119 lines, 834 words
SKILL.md preview
---
name: forge-shape
description: Shape a vague idea into a clear plan through codebase investigation and convergent one-at-a-time questioning. Use when the user has a rough idea or problem that needs specifying before issue creation.
disable-model-invocation: true
allowed-tools: Read, Edit, Write, Bash, Grep, Glob, WebSearch, AskUserQuestion
---

# Shape a Problem

Shape a problem and converge on a plan before creating issues.

## Input

The idea or problem to shape: $ARGUMENTS

Optional: `-- <additional context>` for execution guidance.

If no argument is provided, ask the user what they'd like to shape.

## Process

### Step 1: Investigate Context

Before asking any questions, explore the codebase for related context:
- Find existing implementations, patterns, and constraints relevant to the idea
- Identify integration points, dependencies, and architectural boundaries
- Look for prior attempts or related work (git log, closed issues)

Check for related Issues in the project's Issue tracker — see [issue-operations](_shared/issue-operations.md) for search mechanics per provider.

### Step 2: Shape the Problem

Converge on a shared design concept through one-at-a-time structured questioning. See [shaping-methodology.md](references/shaping-methodology.md) for why one-at-a-time beats batching, how to provide recommended answers without over-anchoring, walking the dependency tree of decisions, when to challenge, and when to stop.

If CONTEXT.md exists, read it — use its vocabulary when framing questions and challenging the user's language.

Ground each question in Step 1 facts, so you never ask what the codebase already answers, and give your recommended answer as "I'd suggest X because Y", not as a decision. **Challenge when warranted:** if an answer conflicts with CONTEXT.md vocabulary, call it out; if it contradicts what the code does, surface it; if it uses vague or overloaded terms, propose a precise canonical term; invent concrete scenarios to stress-test fuzzy boundaries.

**Side effects during shaping** — as terms and decisions crystallize:
- **Resolved term?** Update CONTEXT.md inline — don't batch. Add the term with a tight definition and `_Avoid_` aliases if the user was using multiple words for the same concept.
- **Load-bearing decision?** If it's hard to reverse, surprising without context, and the result of a real trade-off — offer to record it as a short ADR in `docs/adr/`. Most decisions don't qualify. Create the directory lazily.

Stop when the user has accepted recommended answers for several consecutive questions, the remaining questions are taste-level (not decision-level), or the shared design concept is clear enough to summarize.

**Use AskUserQuestion** for each individual question. Do not bundle multiple questions into one prompt — that defeats the methodology.

### Step 3: Explore Approaches (delegate)

**This step is optional.**

If shaping in Step 2 surfaced a clear approach, skip this step and go to Step 4.

If multiple plausible approaches remain after shaping (e.g., the design concept allows for several architectural shapes), delegate approach generation to 2-3 parallel sub-agents, each given a radically different design constraint. The value is in **contrast** — approaches must be structurally different, not variations on the same idea. If the runtime does not support sub-agents, generate the approaches sequentially yourself, deliberately adopting a different constraint lens for each.

Assign each sub-agent one constraint lens (adapt to the problem):
- **Minimal** — smallest change that addresses the core problem
- **Reuse-first** — maximize use of existing patterns and code
- **Extensibility-first** — optimize for future flexibility
- **Performance-first** — optimize for speed or resource efficiency

**Sub-agent instructions:**

> You are designing one approach to a problem, constrained by a specific design lens. Follow your assigned constraint strictly — do not hedge toward a balanced middle ground.
>
> Given the codebase findings and shaped design concept provided as input, propose one approach:
> - One-line summary
> - How it works, referencing specific files and patterns
> - Tradeoffs (what you gain, what you give up)
> - Relative complexity (Low / Medium / High)
> - Risk factors

**Inputs provided to each sub-agent:**
- Codebase facts from Step 1
- Shaped design concept from Step 2
- The specific constraint lens to apply

**Expected output:** One approach per sub-agent, formatted as above.

Always include a **minimal option**. Present the contrasting approaches and let the user choose, combine, or reject all of them.

### Step 4: Summarize Plan

Produce a structured summary using the output format below. This summary is the input for `forge-create-issue`.

The summary is *evidence* of alignment, not the alignment itself. If the user reads the summary and finds nothing surprising, the shaping worked.

## Output Format

```markdown
## Problem Statement
[1-2 sentences grounded in what was discussed]

## Chosen Approach
[Summary of the shaped design concept]

## Scope Boundaries
- In scope: [what this covers]
- Out of scope: [what this explicitly does not cover]

## Suggested Issue Breakdown
- [ ] Issue 1: <type>(<scope>): <description>
- [ ] Issue 2: <type>(<scope>): <description>

## Side Effects
- CONTEXT.md: <terms added or updated>
- ADRs: <decisions recorded, if any>
```

## Guidelines

- **Problem over solution** — clarify what's wrong before proposing how to fix it
- **Stay grounded** — reference specific code, files, and patterns, not abstractions

## Related Skills

**Next step:** Use `forge-create-issue` to turn the plan into Issues.

## Example Usage

```
/forge-shape the app is slow on mobile
/forge-shape we need better error handling
/forge-shape the authentication flow -- we've had security concerns, focus there
```
Files in this package (3)
  • SKILL.md 6 KB
  • _shared 1 KB
  • references/shaping-methodology.md 2 KB

Versions

The database has no other skills named forge-shape.

Database snapshot: 13.11.2026 · package version e2954c95d074 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100brainstorm-beagle
    Use when the user has a fuzzy idea and wants to shape it into a concrete project spec before planning or building. Triggers on: \"brainstorm this\", \"I have an idea for...\", \"help me think through this project\", \"what should I build\", \"spec this out\". Also catches vague…
  • 100forge-create-issue
    Collaboratively plan and create well-structured Issues through interactive discussion (GitHub, markdown plan/ folder, or other providers). Use when the user wants to create an Issue, report a bug, or scope out work that is already understood — use forge-shape first when the idea is still vague.
  • 100v1-interview-me
    Use when an idea, feature request, or ticket needs structured questioning before planning. Triggers on "interview me", "flesh out this idea", or "help me spec this".
  • 100shape
    Turn a rough idea into a plan before anything is built. Interviews the user in rounds, settles scope and stack, writes a short design doc and waits for approval. Use for a new project, an initial idea, a stack choice, or when the user says shape, grill or stress-test this.
  • 90grill-me
    Interview the user one question at a time to pin down a vague idea, feature or plan before any code is written. Use when the user says "grill me", wants to think a design through, or the request is too fuzzy to plan.
  • 100bmad-forge-idea
    Test a half-formed idea in a questioning conversation, with different personas probing its weak points, until the user can act on it or drop it with confidence. Optionally writes a short brief for planning skills to build on. Use when the user says 'forge an idea',…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.