spec-simulate
Use this skill to stress-test a spec before implementation by reading the spec,
reading the relevant source, mentally implementing it end to end, and grading
whether the spec is ready.
Default to review-only. Do not edit source code unless the user explicitly asks
for implementation. If the user asks to apply findings, edit the spec only.
Workflow
- Resolve the spec and goal.
- Identify the spec path, target behavior, and stated grading criteria.
- If the spec path is missing and cannot be inferred from the current task,
ask one concise question.
- Read the implementation context.
- Read the spec first.
- Read the source files, tests, helpers, data types, and existing APIs the
spec names or clearly depends on.
- Verify current behavior from code instead of relying on the spec's claims.
- Simulate implementation end to end.
- Walk through the concrete code changes the implementer would make.
- Check call paths, data contracts, cache/state ownership, error handling,
migration/backfill behavior, and tests.
- Treat "I would need to decide X while coding" as a spec gap.
- Grade the spec.
correct: whether the spec accomplishes the user's desired behavior and
avoids wrong behavior or missed cases.comprehensive: whether the spec is enough to implement end to end without
ambiguity, including tests and verification.simple: whether the spec uses the existing codebase's simplest viable
path instead of duplicating logic or introducing unnecessary abstractions.
- Classify findings.
- Major: anything that can cause incorrect behavior, failed validation, data
loss, security/privacy risk, incompatible contracts, or an implementation
blocker.
- Minor: clarity, test expansion, naming, or simplification feedback that
improves the spec but does not block implementation.
- If asked to apply findings, patch the spec.
- Apply major findings first.
- Keep changes scoped to the reviewed spec.
- Re-run a quick simulation pass after edits when practical.
Output
Use this shape for a review-only pass:
correct: yes/no, with caveats
comprehensive: yes/no, with missing cases
simple: yes/no, with simplification opportunities
Major findings:
- ...
Minor findings:
- ...
If there are no major findings, say that explicitly. Keep the report focused on
spec changes that would affect implementation.
Loop Mode
When the user asks for a loop or repeated simulation pass:
- Run up to three passes.
- After each pass, apply major findings to the spec if the user asked for
fixes.
- Stop early when a pass reports no major findings.
- In the final report, include the number of passes and whether major findings
remain.
1---2name: spec-simulate3description: Simulate implementing a spec against the real source code, then grade the spec as correct, comprehensive, and simple. Use only when explicitly invoked as $spec-simulate or when the user asks to simulate implementation from a spec.4---56# spec-simulate78Use this skill to stress-test a spec before implementation by reading the spec,9reading the relevant source, mentally implementing it end to end, and grading10whether the spec is ready.1112Default to review-only. Do not edit source code unless the user explicitly asks13for implementation. If the user asks to apply findings, edit the spec only.1415## Workflow16171. Resolve the spec and goal.18 - Identify the spec path, target behavior, and stated grading criteria.19 - If the spec path is missing and cannot be inferred from the current task,20 ask one concise question.212. Read the implementation context.22 - Read the spec first.23 - Read the source files, tests, helpers, data types, and existing APIs the24 spec names or clearly depends on.25 - Verify current behavior from code instead of relying on the spec's claims.263. Simulate implementation end to end.27 - Walk through the concrete code changes the implementer would make.28 - Check call paths, data contracts, cache/state ownership, error handling,29 migration/backfill behavior, and tests.30 - Treat "I would need to decide X while coding" as a spec gap.314. Grade the spec.32 - `correct`: whether the spec accomplishes the user's desired behavior and33 avoids wrong behavior or missed cases.34 - `comprehensive`: whether the spec is enough to implement end to end without35 ambiguity, including tests and verification.36 - `simple`: whether the spec uses the existing codebase's simplest viable37 path instead of duplicating logic or introducing unnecessary abstractions.385. Classify findings.39 - Major: anything that can cause incorrect behavior, failed validation, data40 loss, security/privacy risk, incompatible contracts, or an implementation41 blocker.42 - Minor: clarity, test expansion, naming, or simplification feedback that43 improves the spec but does not block implementation.446. If asked to apply findings, patch the spec.45 - Apply major findings first.46 - Keep changes scoped to the reviewed spec.47 - Re-run a quick simulation pass after edits when practical.4849## Output5051Use this shape for a review-only pass:5253```markdown54correct: yes/no, with caveats55comprehensive: yes/no, with missing cases56simple: yes/no, with simplification opportunities5758Major findings:59- ...6061Minor findings:62- ...63```6465If there are no major findings, say that explicitly. Keep the report focused on66spec changes that would affect implementation.6768## Loop Mode6970When the user asks for a loop or repeated simulation pass:71721. Run up to three passes.732. After each pass, apply major findings to the spec if the user asked for74 fixes.753. Stop early when a pass reports no major findings.764. In the final report, include the number of passes and whether major findings77 remain.
kevinslin