diff --git a/docs/JOURNAL.md b/docs/JOURNAL.md index c562cdd..10b2943 100644 --- a/docs/JOURNAL.md +++ b/docs/JOURNAL.md @@ -11181,3 +11181,131 @@ Deferred to 22b.4: - **21'h, latency methodology, FnDef::synthetic, Boehm full retirement, closure-pair slab/pool, deferred richer integration paths.** Unchanged from 21'g. + +## 2026-05-09 — Skill system live (orchestration meta-iteration) + +The five-skill development pipeline shipped today, formalising the +existing iter-cycle workflow as durable artefacts plus +context-isolated subagent dispatch. + +**Spec:** `docs/specs/2026-05-09-skill-system.md`. +**Plan:** `docs/plans/2026-05-09-skill-system-buildout.md`. + +### What landed + +- Five `SKILL.md` files under `skills//`: + - `skills/brainstorm/` — milestone spec generator (hard-gate + before plan) + - `skills/plan/` — spec → bite-sized plan (No-Placeholders rule) + - `skills/implement/` — plan execution with two-stage review + (spec compliance → code quality) + - `skills/audit/` — milestone-tidy with bench-regression gate + - `skills/debug/` — RED-first bug diagnoser, four-phase Iron Law +- All six existing agents migrated to `skills//agents/`: + implementer + tester under `implement`; architect + bencher + + docwriter under `audit`; debugger under `debug`. `agents/` + retains only `README.md` (rewritten as a pointer roster). +- `.claude/agents/{implement,audit,debug}` symlinks tracked in git + for subagent-type discovery on clone. +- `CLAUDE.md` split: 294 → 245 lines. Bug-fix TDD rules, + iter-cycle / tidy-iter / performance-regression sections, and + the feature-acceptance-criterion detail moved into the relevant + skill files; CLAUDE.md keeps headline rules and one-line + pointers. + +### Vocabulary change + +New artefacts use **milestone** (formerly "family") and +**iteration** (formerly "iter"). Legacy JOURNAL entries are NOT +retroactively renamed — they stay in their original wording. New +entries from this point forward use the new vocabulary; commit +messages and JOURNAL section titles will alternate during the +transition until the next milestone closes. + +### Pipeline contract + +``` +brainstorm -> docs/specs/.md +plan -> docs/plans/.md (per iteration) +implement -> per-task commits + JOURNAL entry +audit -> drift report + bench results (mandatory at + milestone close) +debug -> RED-test commit, hands to implement (mini-mode) +``` + +Each stage commits its artefact before handing off; this makes +every stage independently revertable. + +### Skipping rules (codified) + +- `brainstorm` may be skipped for tidy / bug-fix / trivial-mechanic + iterations; **never** at milestone start. +- `plan` may be skipped for bug fix (RED test is the plan) / + trivial mechanic; **never** for a standard iteration. +- `audit` is **mandatory** at milestone close; deferral requires + an explicit JOURNAL entry naming reason + re-run date. +- `debug` is **mandatory** for any observable bug; trivial bugs + still get RED first. + +### Why this exists (motivations recorded) + +Two concrete goals named by the user: + +1. **Formalisation of the development cycle.** Discipline that + was scattered across a 294-line CLAUDE.md, agent reading lists, + and the orchestrator's habits is now in named skills with + trigger conditions and skipping rules. Future-me cannot + accidentally diverge from existing practice without explicitly + violating a named rule. +2. **Context relief.** Skills route work to subagents (per + `skills/implement` and the upstream + `superpowers:subagent-driven-development` pattern). Subagents + work in isolated context windows; the orchestrator only sees + their reports. Long milestones no longer have to fit a single + main-context window. + +The user remains the boss — skills are sharper tools, not a +replacement for orchestrator judgement. The "Direction freedom" +and "When NOT to delegate" sections of CLAUDE.md still apply. + +### Rationalisation tables — pressure-tested baselines + +The five skills were drafted from baseline pressure scenarios run +against a general-purpose subagent without any skill loaded. The +baseline showed strong existing discipline (the project's +CLAUDE.md was already doing its job), so the skills' value-add is +discoverability + context-relief + survival of the CLAUDE.md split, +not novel rule-enforcement. The pressure-test transcripts informed +the `Common Rationalisations` tables in each SKILL.md. + +VERIFY/REFACTOR subagent passes per skill were skipped on the +build-out iteration — pragmatic, given the baselines were already +compliant. If a real-world milestone surfaces skill bugs the +baselines missed, those become follow-up iterations on the +relevant skill. + +### Open follow-ups + +- **First end-to-end exercise.** The next milestone (post-22b / + post-22c) is the first one routed entirely through the skill + pipeline. Expect minor skill bugs to surface; each becomes a + follow-up iteration on the relevant SKILL.md. +- **`ailang-docwriter` rare-tool check.** Now under + `skills/audit/agents/` but invoked rarely. If rustdoc drift + turns out to be its own recurring concern with its own cadence, + it may earn a dedicated skill (`document`?) later. For now, + audit owns it. +- **22b.2 typeclass typecheck arms.** Unchanged from the 22b + queue — picks up after this orchestration iteration closes. + +### Non-goals + +- Renaming `iter` to `iteration` across legacy JOURNAL entries. + Cost > benefit; legacy stays. +- Self-applying the new skills retroactively to in-flight 22b + iterations. 22b stays in its current shape; 22b.2 onwards run + through the new pipeline if 22b is paused; otherwise the next + milestone is the first consumer. +- Per-skill TDD pressure-tests (RED + 3 GREEN/REFACTOR runs each) + on the build-out iteration. Deferred to a follow-up audit if the + first end-to-end exercise reveals gaps.