mgratzer/forge/forge-shape

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 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.

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.

When the decision is how something looks (a screen, an email, a character, a brand mark), a board answers it better than a question: run design rounds. Each design round takes the place of one question.

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: Hand Off Side Effects

When shaping changed CONTEXT.md, added ADRs, or wrote a design spec, never leave those edits stranded in the shaping checkout. Commit them from a temporary worktree on a new docs/<slug> branch cut from the fetched default branch, so the shaping checkout keeps its branch: carry over only the shaping changes (the CONTEXT.md changes, the new ADR files, design spec and boards beside it as written), commit with a docs(context): <description> message, push, and open a docs PR. Then remove the worktree and restore the shaping checkout's originals (CONTEXT.md as it was, or absent if shaping created it; no new ADR, spec or board files), so a later pull there isn't blocked. The PR can merge before the Issues are implemented.

Step 5: Summarize Plan

Produce a structured summary using the output format below, with the Step 4 PR under Side Effects. This summary is the input for forge-create-issue.

Slice the Suggested Issue Breakdown vertically per vertical-slicing: each Issue is one thin end-to-end path, never a layer ("backend for comments", "schema first"). Mark each Issue AFK (fully specified for autonomous execution) or HITL (needs human judgment during implementation), and name the Issues it is blocked by, so create-issue can link them. Add a dependency order view under the checklist when visuals calls for one; the checklist stays, since create-issue reads it.

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> (AFK)
-[ ] Issue 2: <type>(<scope>): <description> (HITL, blocked by Issue 1)
 
[Dependency order view, if any]
 
## Side Effects
-CONTEXT.md: <terms added or updated>
-ADRs: <decisions recorded, if any>
-Design: <spec path, design rounds run, direction chosen, if any>
-PR: #<number>, or "none" when nothing changed

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