global-skills/skills/spec/SKILL.md

name, description, concerns

name	description	concerns
spec	Sole mutator of SPEC.md at project root. Creates new specs, distills specs from existing code, amends sections (§G, §C, §I, §R, §V, §T, §B), and records bugs via backprop in Caveman dialect. Use when asked to "write spec", "new spec", "amend spec", "distill spec", or "spec this".	system-one-balance

Spec — SPEC.md Mutator

The sole mutator of SPEC.md. Other skills produce material (grill → §G/§C, research → §R, review → §V, deepen → §I/§T); spec writes it. All sections follow Caveman encoding.

---

Phase 0: Setup and Protocols

1. Review specification format:
   • Check repo root for FORMAT.md, or consult references/format.md.
   • Apply caveman encoding rules across all section writes.
2. Section Invariants:
   • §G (Goal): 1 line, Caveman dialect.
   • §C (Constraints): Tech stack, out-of-scope declarations.
   • §I (Interfaces): External membranes (api, cmd, env).
   • §R (Research): External sourced findings (optional).
   • §V (Invariants): Monotonically numbered V1, V2, ...
   • §T (Tasks): Pipe table (id|status|task|cites), status ., ~, x.
   • §B (Bug Log): Pipe table (id|date|cause|fix).

---

Phase 1: Ingest and Check

Inspect project state and user intent to dispatch the mode:

1. No SPEC.md exists AND idea provided → NEW
2. No SPEC.md exists AND from-code requested → DISTILL
3. SPEC.md exists AND request starts with bug: → BACKPROP
4. SPEC.md exists AND request starts with amend → AMEND
5. SPEC.md exists with no args → Prompt user for desired mode.

---

Phase 2: Processing (Core Logic)

Mode 1: NEW (Idea → Spec)

1. Extract single-line goal → §G.
2. List user stated and implied constraints → §C.
3. List external boundaries and surfaces → §I.
4. Include §R only if external research ran; otherwise omit.
5. Propose initial testable invariants → §V (V1, V2, ...).
6. Break goal into ordered sequential tasks → §T pipe table with status ..
7. Initialize empty §B table header (id|date|cause|fix).

Mode 2: DISTILL (Codebase → Spec)

1. Walk repository: infer §G from README/entrypoint, §C from stack/lockfiles.
2. Enumerate exported APIs, CLI commands, and env vars → §I.
3. Derive behavioral invariants from existing tests → §V.
4. Create tasks for known TODOs or untested edge cases → §T.
5. Flag uncertainties with ? for user confirmation.

Mode 3: BACKPROP (Bug → §B + §V)

1. Parse bug description and identify root cause in code.
2. Formulate a testable invariant preventing recurrence → draft V<next>.
3. Append row to §B table: B<next>|<date>|<cause>|V<N>.
4. Append new invariant to §V.
5. Update or add tasks in §T if behavior changes.

Mode 4: AMEND (Targeted Edit)

1. Read the specified section (§G, §C, §I, §V, §T, or §B).
2. Show current content and propose the exact modification.
3. Never rewrite sections the user did not specify.

---

Phase 3: The System One Balance Pass

• Augment, Don't Handcuff:
  • Show a clear diff before applying changes.
  • Do NOT trigger automatic build loops upon saving; require explicit user intent to proceed to /build.
  • Avoid ceremony for minor amendments: apply targeted updates swiftly.

---

Phase 4: Output Execution & Verification

1. Write or update SPEC.md at project root.
2. Verify:
   • Section identifiers (§G, §C, §I, §V, §T, §B) match canonical format.
   • Numbering in §V and §B is monotonic with no reused IDs.
   • All §T rows cite their respective dependencies in the cites column.
3. Present the diff/file and suggest next action: /review for high-blast-radius specs, or /build for execution.