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 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 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.
Loop until the design concept is clear:
- Ground the next question in Step 1 facts — never ask what the codebase already answers
- Ask one question with your recommended answer (phrase as "I'd suggest X because Y", not as a decision)
- Wait for the user's response
- Challenge when warranted — if the 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.
- Adjust your understanding and pick the next question
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
## 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