sakura-spec

name	sakura-spec
description	Convert a project idea, feature request, or defect goal into an executable product specification and acceptance contract. Use before development when goals, scope, observable behavior, or evidence are unclear; do not use for technical research, implementation planning, or coding.

Sakura Spec

Role

Convert natural-language intent into a development contract that the current project can implement and verify.

Use When

• A new project or feature begins as a short idea.
• Requirements, non-goals, constraints, or acceptance conditions are unclear.
• The current request may conflict with an existing specification.
• A defect repair first needs the correct expected behavior.

Do Not Use When

• The specification and acceptance contract are complete and the task is implementation only.
• The user requested explanation or read-only inspection.
• The active problem is technical selection, coding, verification, or final review.

Inputs

• The user goal, target user, and expected experience.
• Verified product and technical facts from the current project.
• Existing docs/project/PRODUCT_SPEC.md, ACCEPTANCE.md, and applicable decisions.

Outputs

• An updated docs/project/PRODUCT_SPEC.md.
• docs/project/ACCEPTANCE.md with an acceptance item for every Must requirement.
• Explicit assumptions, non-goals, and material open decisions.
• A handoff to sakura-research or another selected next skill.

Workflow

1. Define one primary goal, the target user, and the core scenario.
2. Separate verified facts, requirements, reversible assumptions, and user decisions.
3. Express every Must requirement as observable user behavior.
4. Define reproducible evidence for every Must requirement.
5. Cover non-goals, data, permissions, compatibility, and applicable error states.
6. Check the specification against verified project facts.
7. When an existing system is the parity target, classify the requested clone or compatibility boundary and create docs/replication/REPLICATION_SCOPE.md without guessing architecture levels.
8. Create a short handoff without selecting an unverified technical solution.

Read spec-template.md when creating or substantially revising a specification. Read requirements-checklist.md before handing the specification off.

Quality Gate

• The specification has one primary outcome and excludes optional enhancements.
• Every Must requirement maps to an acceptance item.
• Requirements describe behavior instead of disguising implementation choices as product needs.
• Non-goals, permissions, data, and applicable failure states are explicit.
• Unknown information remains labeled as unknown.
• A replication request identifies whether the user requires interface, behavior, protocol, runtime, or exact parity without reducing exact parity to UI similarity.

Failure and Fallback

• Use minimal reversible assumptions for ordinary information gaps.
• When information is severely incomplete, produce the smallest valid specification skeleton and open decisions instead of forcing a full plan.
• Ask the user only when a decision materially affects direction or risk.

Upstream and Downstream

• Upstream: the user request, sakura-dev routing, or a defect goal.
• Downstream: sakura-research by default, or sakura-plan when the user explicitly skips research.

Handoff

State whether the specification and acceptance contract are ready, which files changed, material decisions, open issues, risks, and the technical questions for the next stage.