cy-create-spec

Create Spec

Use for a requested specification, not as a prerequisite to an ordinary fix. Author _spec.md with Product and Technical parts and the applicable companion contracts under .compozy/tasks/<slug>/.

1. Reuse the user's decisions, existing spec, and current research. Inspect relevant code/contracts for unresolved questions. Market research is needed only for a market/product uncertainty or an explicit request; delegation is optional and bounded.

2. State the motivating problem, observable outcome, scope, and non-goals. Ask focused questions only for decisions the evidence cannot settle, always in the format from references/grill-protocol.md; apparent simplicity is not evidence. An approved direction satisfies the product checkpoint; do not repeat an interview or approval already completed. For an open-ended product interview, use the relevant branch of references/grill-protocol.md.

3. Write Part I and _user_stories.md from references/spec-template.md and references/user-stories-template.md. Product requirements may name a technology when it is an actual public contract or fixed user constraint; incidental implementation belongs in Part II.

4. Define the changed public surface before its internal implementation: _dx.md uses references/dx-template.md; UI-bearing work uses _uiux.md and references/uiux-template.md. For an internal-only spec, a brief no-public-surface entry is sufficient. Preserve named visual references and production owners.

5. Write Part II with the concrete contracts the design changes. Read only relevant ADRs/analysis. Use references/adr-template.md for consequential decisions with real alternatives; a routine choice needs no standalone ADR. Document the target project's compatibility policy for changed user state and public surfaces, including lossless migrations, deprecation/removal plans, delete targets, and one owning impact analysis with links from companions. If no policy exists, state the proposed guarantees and unresolved decisions explicitly.

6. Write _tests.md using references/tests-template.md: distinct invariants, owning suites, inputs/results, and necessary integration journeys. Reuse existing coverage; no quotas per component, error class, or layer.

7. Write _slices.md, the delivery order that spec delivery reads:

   | Slice | Layer    | Depends on | Scope           | Spec refs |
   | ----- | -------- | ---------- | --------------- | --------- |
   | S1    | backend  | none       | Export contract | US-001    |
   | S2    | frontend | S1         | Export dialog   | US-002    |
   

   One row per independently verifiable slice. Layer names the owning layer, Depends on lists slice IDs or none, and Spec refs cites the stories or sections it delivers. Choose slice count from dependencies and risk, and let unrelated slices run in parallel. The first slices should reach the earliest useful end-to-end outcome.

8. Perform an inline self-check: verify that the motivating outcome is covered, public contracts agree across companions, changed interfaces use the project's language, each test invariant has an owning suite, every story belongs to a slice, slice dependencies are acyclic, and existing input/reference paths resolve in the target project or this skill's bundled resources. Mark new files and output destinations as planned; they need not exist before implementation. Record inapplicable sections and unresolved decisions explicitly. Check the earliest useful end-to-end outcome.

9. Save reviewable files and summarize unresolved decisions. After the user approves the saved spec, offer the optional peer review in references/peer-review.md. Do not start implementation merely because spec writing is complete.

Templates are section guides: keep shared outcome/contract content, omit irrelevant sections or record a short reason where a downstream schema requires a slot. Read each reference when its branch is used, not the whole package. Maintain a concise File References index naming contract inputs and why each matters; slice briefs copy their relevant subset. Preserve requested scope; narrowing an accepted motivating problem requires the user's recorded decision.

For updates, edit affected sections/companions only. Missing or contradictory inputs are resolved from user decisions and current policy; report a genuinely blocking missing contract without inventing it.