Spec Shaping

Spec Shaping

Transform product ideas into well-scoped specs and actionable sprint plans. This skill supports two complementary modes:

1. Interview mode: Probe the problem space until a clear, narrow spec emerges
2. Sprint breakdown mode: Decompose a spec into atomic tasks and demoable sprints

When to Use

• User has a rough product plan or idea that needs scoping
• User needs help thinking through implementation details, UI/UX, or tradeoffs
• User has a spec ready to break into sprints and tasks
• User wants to validate whether a problem is well-framed before building

Document Management

Treat specs and sprint plans as living documents. Use the following standards to ensure consistency and "freshness".

1. File Operations (Search, Location, Updates)

• Search First: Before creating a new file, search for existing specs for this project.
• Update vs. New:
  • Update: If the "Identity" of the project is the same (same core problem, just refining/pivoting implementation), update the existing spec.
    • Action: Rename file to today's date + update Metadata.
  • New: If the problem definition has fundamentally changed, or the solution direction is a complete "burn it down" restart, create a new spec.
• Output Location (Adaptive):
  1. Scan for: specs/, planning/, docs/specs/, product/.
  2. If found: Use that directory.
  3. Default: Create and use specs/.
  4. Vaults: If external, check agents.md/claude.md for overrides.

2. File Standards (Naming, Metadata, Content)

• Naming: [Semantic name] - [YYYY-MM-DD].md
  • Specs: Checkout flow spec - 2024-03-25.md
  • Sprints: Checkout flow sprints - 2024-03-25.md
• Frontmatter:

  ---
  status: [Planned | In Progress | Completed]
  last: [YYYY-MM-DD]
  ---
  

• Context Header (Required):

  > [!NOTE] > **Context**: [Why was this updated? e.g. "Pivot to V2"] > _This document reflects the product thinking at the time of the last update._
  

• Changelog: Keep a ## Changelog at the bottom. Initialize if missing. Only log significant changes (e.g. scope pivots). Ignore trivial edits.

Interview Mode

Read the plan file and interview the user in detail about technical implementation, UI & UX, concerns, tradeoffs, etc. Make sure questions are not obvious.

Interview Principles

1. Narrow before expanding: Push to narrow the problem until it can be described in one clear sentence. Vague scope ("build a calendar") leads to endless shaping. Precise scope ("show empty time slots between existing events") enables real solutions.
2. Surface complexity early: Ask "what could make this harder than it sounds?" and "where are the hidden dependencies?" The goal is to reveal time bombs before they're in the middle of a build, not after.
3. Distinguish understanding from justification: Watch for the anti-pattern where someone has already decided what to build and is looking for data to justify it. Ask why this problem matters before discussing solutions.
4. Probe the adjacent user: If this is user-facing, ask who the next user is — the one just outside the current target. What would need to be different for them?

Interview Process

Be very in-depth. Continue interviewing until you're confident the problem is well-framed and the key risks are surfaced. Then write the spec to the file.

A good spec should be shapeable— someone should be able to read it and describe the solution in ≤9 major components. If they can't, the problem isn't narrow enough yet.

Sprint Breakdown Mode

Read the spec file and break the project down into sprints and tasks.

Core Principles

1. Atomic tasks: Every task should be an atomic, committable piece of work that can be completed, reviewed, and merged independently.
2. Compositional clarity: Small atomic tasks should compose up into a clear goal for the sprint. If the relationship between tasks and the sprint goal isn't obvious, add a brief "Sprint Goal" statement.
3. Demoable sprints: Every sprint should result in a demoable piece of software that can be run, tested, and built on top of previous sprints.
4. Clear validation: Each task must include explicit validation criteria — tests where applicable, or another concrete verification method (e.g., "Validation: API returns 200 with expected payload", "Validation: Component renders correctly in Storybook").
5. Dependencies first: Order tasks so dependencies are completed before the work that relies on them.
6. Fixed time, variable scope: Sprints are time-boxed appetites, not scope commitments. If something doesn't fit, shape it smaller — don't extend the timeline.
7. Budget for understanding: Reserve ~10-20% of sprint capacity for de-risking future work — spikes, research, or validation that will speed up the next sprint.

Output Structure

Structure your output so it remains malleable as the project evolves:

• Stable identifiers: Give tasks IDs (T1, T2, etc.) so they can be referenced and reshuffled between sprints without losing context.
• Traceability: Link tasks back to spec sections so changes to the spec can be traced to affected tasks.
• Visible dependencies: Make it clear which tasks depend on others.

Adapt the specific format to what makes sense for this project — a simple list may suffice for small projects, while complex projects might benefit from a task registry table with sprint groupings. Use your judgment.

Sprint Breakdown Process

1. Read the spec thoroughly. Identify natural section boundaries for traceability.

2. Create the task registry first — focus on atomicity and dependencies.

3. Group tasks into sprints, ensuring each sprint is demoable.

4. Self-review with these lenses:

   • Are any tasks too large to complete in a single focused session?
   • Are there missing or circular dependencies?
   • Is each validation criteria concrete and verifiable?
   • Could a developer pick up any task and know exactly what "done" looks like?
   • Does each sprint have a clear demo scenario?
   • Shaping smell test: Can you describe the entire sprint in ≤9 major scopes? If not, the spec may need more narrowing before breaking it into tasks.

5. Revise based on your review.

6. Write the final sprint plan to a markdown file alongside the spec (e.g., Checkout sprints - 2024-03-25.md).

Optional: Subagent Review

For large or complex specs with many interdependencies, consider using a subagent to review the sprint plan with fresh context. This provides a "second set of eyes" unpolluted by the main conversation. The subagent should:

• Review the sprint plan for gaps, circular dependencies, or tasks that are too large
• Suggest improvements to task scoping or sprint groupings
• Flag any validation criteria that are vague or unverifiable

Use your judgment — this is most valuable for hairy, high-stakes specs where a deeper audit is worth the overhead.

Explicitly Out of Scope

• Time estimates: Do not estimate duration. The human will layer in timeline context.
• Resource allocation: Do not assign tasks to people or roles unless explicitly requested and given enough context to do so.