shape

# Shape — Auto-Grill to PRD Take a rough product idea and turn it into a complete PRD in one shot. No interactive grilling — Claude walks the decision tree itself, answers each question with software-engineering best practices, streams the Q&A live so you can spot bad assumptions, and writes the PRD. Use `/shape` when you trust Claude's judgment and want speed. Use `/grill-me` + `/write-a-prd` when you want hands-on control over every decision. ## Pipeline Position | Step | Command | What It Does | |------|---------|--------------| | 1a | `/grill-me` + `/write-a-prd` | Manual path — interactive interview, then PRD | | 1b | **`/shape`** | **Fast path — auto-grill + PRD in one shot** | | 2 | `/prd-to-issues` | Break the PRD into vertical-slice sub-issues | | 3 | `/ralph` | Implement each sub-issue autonomously with TDD + code review | `shape` produces the same PRD format as `write-a-prd`, so `/prd-to-issues` and `/ralph` consume its output without changes. ## Instructions When the user invokes this skill: ### 1. Capture the idea If the user passed an idea as an argument, use it. Otherwise ask once: > What do you want to build? (one paragraph is fine) Then proceed without further interactive questions until step 8. ### 2. Explore the codebase Before answering anything, ground your decisions in reality: - Read `README.md`, `CLAUDE.md`, and any architecture docs - Identify existing modules, conventions, test patterns, and prior art the feature should match - Verify any factual assertions in the user's idea — don't trust them, check - Note the language, framework, test runner, and directory layout If there is no codebase (empty directory or greenfield), skip to step 3 and record this in the PRD's Further Notes. ### 3. Walk the decision tree For each branch below, generate the questions a thorough engineer would ask, then answer each one yourself. **Do not skip a branch even if it feels obvious — that is the entire point of this skill.** - **Actors & user stories** — who uses this, what they want, what success looks like - **Happy-path flow** — primary interaction step by step - **Edge cases** — empty inputs, large inputs, concurrent access, partial failures, network errors, permission denied, missing data, unicode/encoding, time zones - **Data model & schema** — entities, relationships, indexes, migrations - **Module boundaries** — deep modules, public interfaces, what stays internal - **API contracts** — request/response shapes, error codes, idempotency, versioning - **Testing strategy** — what to test, what to mock (only at boundaries), prior art in the repo - **Security** — authn/authz, input validation, secrets, rate limiting - **Observability** — what to log, what to surface as metrics - **Out of scope** — explicit non-goals to prevent scope creep - **Dependencies & blockers** — what must exist first ### 4. Best-practice defaults When self-answering, prefer: - **Boring over clever** — simple, well-understood patterns - **Deep modules** (Ousterhout) — wide functionality behind a simple, stable interface - **Match the codebase** over external standards — project conventions win - **TDD-friendly design** — testable through public interfaces, not internals - **Validate at system boundaries** — trust internal callers, fail loudly at the edge - **YAGNI** — no speculative abstractions, no features the user didn't ask for - **Parameterized queries**, never string concatenation - **Rate limit auth endpoints** - **Never log secrets, tokens, or PII** - **Mock only at system boundaries** (external APIs, DBs, time, randomness, filesystem) — never mock internal collaborators **Codebase facts always beat generic best practices.** If the project already does X, the answer is X. ### 5. Stream the Q&A live For every decision, emit a block in this exact format as you make the call — do not batch: ``` Q: <the question> A: <the chosen answer> Why: <one sentence — cite a codebase reference if relevant> ``` This is the user's chance to spot a bad assumption early. ### 6. Write the PRD Use this template exactly. It matches `/write-a-prd`, so the rest of the pipeline accepts it unchanged. ```markdown ## Problem Statement The problem the user is facing, from the user's perspective. ## Solution The solution, from the user's perspective. ## User Stories A long, numbered list: 1. As a <actor>, I want a <feature>, so that <benefit> Cover every aspect of the feature surfaced in your decision tree. ## Implementation Decisions - Modules to build or modify - Public interfaces of those modules - Architectural decisions - Schema changes - API contracts - Specific interactions Do NOT include file paths or code snippets — they go stale fast. ## Testing Decisions - What makes a good test here (test external behavior, never implementation details) - Which modules will be tested - Prior art for the tests (similar patterns already in the codebase) ## Out of Scope Explicit non-goals. ## Further Notes Anything else worth recording. ## Decisions Log Every Q/A/Why block from step 5, in the order they were decided. ``` ### 7. Save the PRD locally - Generate a kebab-case slug from the idea (e.g. "rate-limited /healthz endpoint" → `rate-limited-healthz-endpoint`) - Create `./prds/` if it doesn't exist - Write the PRD to `./prds/<slug>.md` - Print the absolute path ### 8. Offer to push to GitHub After saving, ask the user once: > Push this as a GitHub issue? [y/N] On `y`, run: ```bash gh issue create --title "<slug>" --body-file ./prds/<slug>.md ``` Print the issue URL. On `n` or no answer, stop. The local file is enough — the user can push later. ## Rules - **Don't ask the user questions during the decision tree.** The whole point is auto-answering. The only interactive moments are: capturing the idea (if not given) and the GitHub push prompt at the end. - **Don't skip branches.** Even trivial-feeling branches get walked — completeness is the value. - **Codebase facts beat generic best practices.** If the project already does X, X is the answer. - **No speculative scope.** If the user didn't ask for it and the codebase doesn't require it, it goes in Out of Scope. - **The PRD template is fixed.** It must match `/write-a-prd` exactly so `/prd-to-issues` and `/ralph` keep working.