shape-local

name	shape-local
description	Use when you have a rough product idea and want a complete local PRD without sitting through an interactive grilling. Claude walks the full decision tree, self-answers with software-engineering best practices, streams the Q&A live so you can override, and writes the PRD locally using the prd-<phase.sequence> naming convention so /prd-to-tasks and /ralph-local can consume it.

Shape - Auto-Grill To Local PRD

Take a rough product idea and turn it into a complete local 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 to docs/roadmap/prds/.

Use /shape when you trust Claude's judgment and want speed. Use /grill-me + /to-prd when you want hands-on control over every decision.

Pipeline Position

Step	Command	What It Does
1a	/grill-me + /to-prd	Manual path - interactive interview, then local PRD
1b	/shape	Fast path - auto-grill + local PRD in one shot
2	/prd-to-tasks	Break the PRD into local vertical-slice task specs with parent-prd metadata and a PRD Ralph task block
3	/ralph-local	Implement PRD-listed local tasks autonomously with TDD, local review gates, final PR creation, CodeRabbit iteration, and human-only merge

shape produces the same local PRD format expected by /prd-to-tasks. It does not create task specs itself and does not create GitHub issues.

Productizing Design Prototypes

When the idea is grounded in a visual prototype, Figma export, Claude Design JSX, or static HTML mockup:

• Treat the artifact as a design contract, not production-ready implementation.
• Inspect supporting design files such as tokens, seed data, shell/layout files, component variants, and interaction mocks.
• Call out every prototype-only dependency in the PRD: globals, static fixture data, hardcoded status text, no-op callbacks, fake filters/selectors/actions, fixed desktop dimensions, inline styling, and missing accessibility states.
• Require real data/action wiring or explicit disabled/removed states for every visible control.
• Include human-usability acceptance criteria: responsive layout, keyboard/focus behavior, loading/empty/error states, and accessible labels/contrast.

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 the PRD is drafted.

2. Explore The Codebase

Before answering product and implementation questions, ground your decisions in reality:

• Read README.md, CLAUDE.md, DESIGN.md (root only), ARCHITECTURE.md in all apps/ and packages/.- Identify existing modules, conventions, test patterns, and prior art the feature should match.
• Verify factual assertions in the user's idea from local code/docs when possible.
• Note the language, framework, test runner, and directory layout.
• Read package.json at the package/app root to know dependency versions and scripts.
• Search affected app/package changelogs for related prior work.
• Read relevant ARCHITECTURE.md files, especially gotchas.
• Read root DESIGN.md whenever the PRD touches apps/web or packages/ui.
• Never read .env or .env.local; use .env.example files for environment variable discovery.
• Use a plain ls * in the key directories to surface relevant files and docs.

If there is no codebase or the directory is greenfield, skip codebase grounding and record this in the PRD's Further Notes.

3. Choose The PRD ID

PRD ids use a separate namespace from task ids.

Use this convention:

• PRD id: prd-4.86
• PRD filename: docs/roadmap/prds/prd-4.86-cap-table-sidebar-and-designed-subpages.md
• Future task ids generated by /prd-to-tasks: 4.86.1, 4.86.2, 4.86.3
• Future task parent-prd: "prd-4.86"

Rules:

• Do not use bare numeric ids such as 4.86 as PRD ids.
• Read docs/roadmap/ROADMAP.md and existing docs/roadmap/prds/ before choosing an id.
• Choose an unused prd-<phase.sequence> id that fits the roadmap area.
• If neither docs/roadmap/ROADMAP.md nor existing PRDs exist, use prd-1.1 as the first local PRD and record the greenfield roadmap assumption in Further Notes.
• If the user supplied an id, use it only if it follows prd-<phase.sequence> and does not collide.
• If unsure where the PRD belongs, pick the closest roadmap phase and record the assumption in Further Notes.

IMPORTANT: Before you start the decision tree, invoke the command/skill /ask-questions-if-underspecified to understand the users priority for this task.

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

• Actors and 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 and 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, tenant isolation, logging boundaries
• Observability: what to log, what to surface as metrics
• Out of scope: explicit non-goals to prevent scope creep
• Dependencies and blockers: what must exist first

5. Best-Practice Defaults

When self-answering, prefer:

• Boring over clever
• Deep modules with wide functionality behind a stable interface
• Project conventions over external standards
• TDD-friendly design tested through public interfaces, not internals
• Validation at system boundaries
• YAGNI: no speculative abstractions or features the user did not ask for
• Parameterized queries, never string concatenation
• Rate limiting on auth-sensitive endpoints
• No logging of secrets, tokens, or PII
• Mock only at system boundaries: external APIs, databases, time, randomness, filesystem
• Verify implementations of third-party dependencies or packages by searching online by reading at least 10 independent online resources about the specific implementation of the third-party resource.

Codebase facts always beat generic best practices. If the project already does X, the answer is X.

6. Stream The Q&A Live

For every decision, emit a block in this exact format as you make the call:

Q: <the question>
A: <the chosen answer>
Why: <one sentence - cite a codebase reference if relevant>

Do not batch these blocks. Streaming them live lets the user spot a bad assumption early.

7. Write The PRD

Use this template exactly. It is compatible with /prd-to-tasks and /ralph-local.

---
id: "prd-<phase.sequence>"
title: "<Title>"
status: "ready-for-tasking"
---

## 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 brittle code snippets. Include stable file or module references only when they are necessary for task planning.

## Testing Decisions

- What makes a good test here
- Which modules should be tested
- Prior art for the tests
- Browser/manual QA expectations if no local unit runner exists

## Out of Scope

Explicit non-goals.

## Further Notes

Anything else worth recording, including assumptions made while choosing the PRD id or roadmap location.

## Decisions Log

Every Q/A/Why block from step 6, in the order they were decided.

Do not add a Ralph task block in /shape. /prd-to-tasks creates or updates the Ralph task block after task specs exist.

8. Save The PRD Locally

• Generate a kebab-case title slug from the idea.
• Create docs/roadmap/prds/ if it does not exist.
• Write the PRD to docs/roadmap/prds/prd-<phase.sequence>-<kebab-title>.md.
• Ensure the frontmatter id exactly matches prd-<phase.sequence> from the filename prefix.
• Print the absolute path.

Example:

docs/roadmap/prds/prd-4.86-cap-table-sidebar-and-designed-subpages.md

Rules

• Do not ask the user questions during the decision tree. The whole point is auto-answering. The only interactive moment is capturing the idea if none was provided.
• Do not create task specs in /shape; use /prd-to-tasks for that.
• Do not create GitHub issues.
• Do not skip decision-tree branches.
• Codebase facts beat generic best practices.
• No speculative scope. If the user did not ask for it and the codebase does not require it, put it in Out of Scope.
• The PRD template must stay compatible with /prd-to-tasks and /ralph-local.
• Use the prd-<phase.sequence> id convention.
• Do not use bare numeric task ids as PRD ids.