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