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**: ```yaml --- status: [Planned | In Progress | Completed] last: [YYYY-MM-DD] --- ``` - **Context Header** (Required): ```markdown > [!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.