cavekit-spec
Create, distill, amend, or backprop bugs into project-root SPEC.md using Cavekit FORMAT.md. Use when users invoke /ck:spec, ask to write a Cavekit spec, amend §G/§C/§I/§V/§T/§B, distill a spec from code, or record a bug via backprop.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 16
- Forks
- 9
01 前言 Front Matter
- name
- cavekit-spec
- description
- Create, distill, amend, or backprop bugs into project-root SPEC.md using Cavekit FORMAT.md. Use when users invoke /ck:spec, ask to write a Cavekit spec, amend §G/§C/§I/§V/§T/§B, distill a spec from code, or record a bug via backprop.
03 SKILL.md 正文
cavekit-spec — SPEC.md mutator
This is the sole Cavekit workflow that mutates project-root SPEC.md content beyond task status flips.
Read bundled ../../FORMAT.md before writing or checking spec structure. That file defines the SPEC.md schema, addressing rules, pipe-table rules, and caveman-style encoding for spec content. The bundled FORMAT.md is reference material; the working SPEC.md lives at the user's project root.
Dispatch
Inspect the user's request and project state:
- No
SPEC.mdat project root AND request describes an idea → NEW - No
SPEC.mdat project root AND request includesfrom-code→ DISTILL SPEC.mdexists AND request starts with or clearly meansbug:→ BACKPROPSPEC.mdexists AND request starts with or clearly meansamend→ AMENDSPEC.mdexists and no mode is clear → useask_user_questionto choose mode before proceeding
INPUTS — spec is the sole mutator
The reach-for verbs produce material; cavekit-spec writes it. Sectioned
ownership: ingest each handoff block into the section that verb owns, show a
diff, write on OK. ⊥ rewrite a section the handoff did not name.
- cavekit-grill → sharpened §G + §C
- cavekit-research → §R rows (add the §R section if absent)
- cavekit-review → drafted §V lines + the risk verdict
- cavekit-deepen → §I/§V/§T amendments
§R RESEARCH is optional — create the section only when a research handoff
arrives; omit it otherwise (right-size).
Question protocol
Use ask_user_question whenever Cavekit needs a decision from the user. Do not print prose-only choice lists and wait.
Required cases:
- unclear dispatch mode;
- missing AMEND target or replacement text;
- choosing between multiple plausible edits;
- approving
SPEC.mdmutation after a proposed diff; - deciding whether BACKPROP should add only §B, add §B+§V, or add §B+§V+§T.
Rules:
- Share needed context in normal assistant text before invoking
ask_user_question: current § item, evidence, proposed diff/plan, tradeoffs, and recommendation. - Invoke
ask_user_questiononly after that context is already visible to the user. The question UI must be a decision step, not the place where the plan is explained. - Do not put full plan, diff, evidence, nuanced rationale, or long replacement text in the question string, option descriptions, or previews.
- Keep the
questionfield short: ask only for the decision. - Options are decision controls, not context transport.
- Ask 1-4 grouped questions in one tool call.
- Use 2-4 concrete options per question.
- Put recommended option first and suffix label with
(Recommended)when applicable. - Keep option labels ≤60 chars and headers ≤16 chars.
- Keep option descriptions concise: identify action and key consequence only. Exact § refs are OK; long replacement text belongs in pre-question context.
- If user must supply arbitrary text, ask with concise options and let built-in
Type something.handle custom input; do not invent anOtheroption.
Example for missing amend target/change:
Need amend target/change missing.
Current evidence:
- §V.149 still names prohibited `AgentTool` collapse.
- Code now uses `tin_reactor::Error::Tool(#[from] tin_tools::Error)`.
- `AgentTool` variant should remain forbidden.
Proposed amendment:
- Amend §V.149 to: `V149: tin_reactor::Error::Tool(#[from] tin_tools::Error); AgentTool variant ⊥.`
Tradeoff:
- V149-only fixes spec drift.
- V149 + task adds explicit regression guard if tests do not already cover it.
Then invoke `ask_user_question` separately:
ask_user_question({
questions: [{
header: "Amend target",
question: "Which amendment should apply?",
options: [
{ label: "Amend V149 (Recommended)", description: "Update invariant only; no new task." },
{ label: "Amend + task", description: "Update invariant and add guard task/test." },
{ label: "Different target", description: "Use typed custom answer with exact § ref or text." }
]
}]
})
NEW — idea → spec
Input: user idea.
Steps:
- Extract goal as one caveman-format line → §G.
- List stated or implied non-negotiable constraints → §C.
- List external surfaces the user named or the code clearly exposes → §I.
- Propose initial testable invariants → §V numbered
V1.... - Break goal into ordered tasks → §T pipe table with status
., idsT1..., andcitesentries for relevant §V/§I refs. - Create §B with only header row:
id|date|cause|fix.
Write SPEC.md at project root. Show the full file and use ask_user_question for spec OK? with options like accept, amend, or stop.
DISTILL — code → spec
Walk the current repo. If cavecrew-investigator is available, use it first for read-only compressed repository mapping: public surfaces, package metadata, main entrypoints, tests/assertions, TODOs, config/env/files, and likely invariants. The investigator must return file:line evidence only and must not design, fix, edit, or mutate state. If unavailable, continue with codebase-memory tools when available, then exact reads/search as fallback.
Produce:
- §G: infer from README, package metadata, main entrypoints, or obvious behavior.
- §C: infer stack, language, runtime, and locked constraints.
- §I: enumerate public CLIs, APIs, config files, env vars, files, or package exports.
- §V: derive from tests, assertions, validation code, and security/performance invariants.
- §T: one task per known TODO, missing test, incomplete edge, or uncertain item.
- §B: empty bug log with header row.
Use ? to flag uncertain inferred facts so the user can confirm.
BACKPROP — bug → §B + usually §V
For bug reports, use cavekit-backprop analysis. Then apply approved SPEC.md changes here:
- Parse bug description and root cause.
- Decide whether a new invariant would catch recurrence.
- Append §B row:
B<next>|<date>|<cause>|V<N>or-if no invariant. - Append §V line when useful.
- Add or update §T rows if behavior or tests are now required.
- Show the diff. Apply only after user approval unless the user explicitly requested direct mutation.
Every considered bug gets a §B entry. A §V invariant is preferred when the bug represents a class of recurrence.
AMEND — targeted edit
Input examples: amend §V.3, amend §T, amend interfaces.
- Read the named section or item.
- Show current content.
- Use
ask_user_questionfor desired change if target or replacement is not already specified. - Edit only the named section or item.
- Show diff.
Never silently rewrite sections the user did not name.
Archive-aware ID lookup
When assigning new §V, §T, or §B ids:
- Parse current
SPEC.mdtable/line IDs. - Parse archive comments like
<!-- archive: .cavekit/archive/SPEC-<date>.md §T T1-T12 -->for archived ranges. - Read referenced
.cavekit/archive/SPEC-*.mdfiles when comments exist or ranges/cites are ambiguous. - Use max(current IDs + archive comment ranges + archived SPEC.md IDs) + 1.
- Never restart at
T1,V1, orB1when archived IDs exist.
Archived §V/§I refs remain valid cite targets when an archive comment points to the full text.
Output rules
- Follow bundled
../../FORMAT.md. - Use caveman-style encoding for SPEC.md content only.
- Preserve code, paths, identifiers, URLs, numbers, error strings, SQL, regex, JSON, and YAML verbatim.
- Numbering is monotonic: never reuse §V, §T, or §B ids; include archived IDs in max lookup.
- Escape literal
|in pipe-table cells as\|. §Trows useid|status|task|citesand status values.,~,x.
Boundaries
- Do not edit application code from this skill.
- Do not auto-run
/ck:buildafter spec creation. - Do not commit unless the user explicitly asks in this session.
- Do not require
pi-caveman; Cavekit spec encoding is defined by bundledFORMAT.md.
04 同仓库更多 Skills
why
Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
unslop
Cut AI tells from any writing.
typescript-best-practices
TypeScript best practices. Use when reading or editing any .ts or .tsx file.
technical-writing
Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for /skill:technical-writing or when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages.
teach
Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'.
tdd
Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested.