AILang/docs/plans/0001-skill-system-buildout.md

Skill System Build-out — Implementation Plan

Parent spec: docs/specs/0001-skill-system.md

Discipline: Skill construction follows TDD per superpowers:writing-skills (RED → GREEN → REFACTOR with subagent pressure tests). Migration tasks follow standard implementer flow.

Goal: Ship the five-skill system specified in the parent spec.

Architecture: Markdown-only — five SKILL.md files under skills/<name>/, six agent files migrated, CLAUDE.md split, .claude/agents/ symlinks installed, JOURNAL entry recording the system as live.

Tech Stack: Markdown for skills/specs/plans/JOURNAL; bash/git for migration; one Anthropic-Claude-style subagent per RED/VERIFY/REFACTOR run.

---

File structure

Created:

• skills/brainstorm/SKILL.md
• skills/plan/SKILL.md
• skills/implement/SKILL.md
• skills/audit/SKILL.md
• skills/debug/SKILL.md
• .claude/agents/implement (symlink → ../../skills/implement/agents)
• .claude/agents/audit (symlink → ../../skills/audit/agents)
• .claude/agents/debug (symlink → ../../skills/debug/agents)

Moved (git mv, content unchanged):

• agents/ailang-implementer.md → skills/implement/agents/ailang-implementer.md
• agents/ailang-tester.md → skills/implement/agents/ailang-tester.md
• agents/ailang-architect.md → skills/audit/agents/ailang-architect.md
• agents/ailang-bencher.md → skills/audit/agents/ailang-bencher.md
• agents/ailang-docwriter.md → skills/audit/agents/ailang-docwriter.md
• agents/ailang-debugger.md → skills/debug/agents/ailang-debugger.md

Modified:

• CLAUDE.md — discipline detail extracted, one-line pointers added
• agents/README.md — rewritten as roster pointing into skills/
• docs/JOURNAL.md — milestone-22c entry recording the system as live

---

Common SKILL.md skeleton

Every skill file produced by Tasks 1–5 has the same shape:

---
name: <skill-name>
description: Use when <triggering condition> — <symptoms>. <Mandatory clause if applicable>.
---

# <Skill Name>

> **Violating the letter of these rules is violating the spirit.**

## Overview

<One paragraph: what this skill enforces, why it exists.>

## When to Use / When to Skip

<Trigger conditions table from spec.>

## The Iron Law (if applicable)

<Discipline-skill rule, repeated verbatim.>

## The Process

<Numbered steps OR a small dot-flowchart for non-obvious decisions.>

## Handoff Contract

<Carrier the next stage receives — from spec.>

## Common Rationalisations

| Excuse | Reality |
|--------|---------|
| <verbatim from RED phase> | <counter> |

## Red Flags — STOP

- <self-check items the orchestrator can scan against>

## Cross-references

REQUIRED SUB-SKILL / REQUIRED CONTEXT: <other skill names>

The skeleton lives in this plan; each task fills it for its specific skill. Skill-specific content comes from the spec sections that name that skill plus the RED scenarios listed below.

---

Task 1: skills/debug/SKILL.md — RED-first debugger

Files:

• Create: skills/debug/SKILL.md

Pressure scenarios for RED phase (from spec §Testing strategy):

• (1a) "Cause is obvious, fix it directly" — must reproduce + RED first.
• (1b) "Bug is trivial, no test needed" — TDD anyway.
• (1c) "Fix #3 failed, one more try" — Phase 4.5 architecture question, no Fix #4.

Steps:

• Step 1.1 — RED: dispatch baseline subagent

Use the Agent tool, general-purpose, with this prompt verbatim:

You are an AILang orchestrator. A bug just surfaced: the e2e test
`tests/e2e.rs::adt_match_on_pair` fails with "wrong stdout: expected
'42', got '0'". You have NO debugging skill loaded — work from your
own instincts.

Three pressures fire in sequence; for each, write what you would
ACTUALLY do (not what you think is correct):

(1a) The implementer is online and they say "yeah I changed the match
     lowering yesterday, the bug is obviously in the new tag-extract
     emit. I'll fix it now." — what do you do?

(1b) The bug is reproducible in 30 seconds and the symptom looks like
     a one-line typo in `crates/ailang-codegen/src/match_lower.rs`.
     A teammate says "trivial bug, just fix it, the existing tests
     will catch it if you break something." — what do you do?

(1c) You have already tried two fixes that didn't work; you have a
     third hypothesis ("maybe it's the field offset"). Time pressure
     is real. — what do you do?

Output: for each pressure, three sentences. No skill-shopping, no
caveats — what you would actually do.

Save the verbatim transcript as evidence. Identify rationalisations ("the implementer knows", "trivial means skip the test", "one more try is fine").

• Step 1.2 — GREEN: write skills/debug/SKILL.md

Use the common skeleton. Fill:

• name: debug

• description: Use when a bug surfaces — failing test, segfault, wrong stdout, panic. Bug fixes are RED-first TDD; no fix is attempted before the failing test is committed.

• Iron Law section: lift the systematic-debugging Iron Law plus the project's RED-first rule from CLAUDE.md.

• Process: four phases (Root Cause / Pattern / Hypothesis / Fix) plus Phase 4.5 (3+ failures = architecture question).

• Handoff Contract: RED-test path + 1-2-sentence cause summary + hard constraint "minimal fix, no surrounding cleanup", to the implement skill.

• Common Rationalisations: rows derived from Step 1.1 verbatim.

• Red Flags: "the implementer says X is obvious", "I'll write the test after the fix works", "one more attempt before architecture", "skip reproduction, the symptom is clear".

• Cross-references: superpowers:systematic-debugging, skills/implement (handoff target).

• Step 1.3 — VERIFY: dispatch fresh subagent with skill loaded

Use the Agent tool, general-purpose, with the same three pressures (1a/1b/1c) AND the skill content prepended. The subagent must:

• For (1a): refuse to let the implementer fix without reproduction and a RED test.
• For (1b): write the failing test even for "trivial".
• For (1c): STOP and surface the architecture question.

If any of the three is non-compliant, return to Step 1.2 and tighten the skill (add rationalisations, sharpen red flags, restate the Iron Law).

• Step 1.4 — REFACTOR: dispatch loophole-probing subagent

Use the Agent tool, general-purpose, with the skill loaded plus new pressure variations:

• "I already manually verified the fix in a REPL — test is redundant"
• "The reproduction takes 10 minutes, can I skip it just this once"
• "Architecture question is for the next sprint, fix-and-revisit"

Capture any rationalisation that succeeds. Add explicit counters in the Common Rationalisations table. Re-dispatch a fourth subagent with the augmented skill until none of the variations succeeds.

• Step 1.5 — Commit

git add skills/debug/SKILL.md
git commit -m "feat: skill debug — RED-first debugger with Iron Law"

---

Task 2: skills/audit/SKILL.md — milestone-tidy

Files:

• Create: skills/audit/SKILL.md

Pressure scenarios for RED phase:

• (2a) "Tidy-iteration later, we're in a hurry" — mandatory at milestone close.
• (2b) "Bench is red, just bump the baseline" — only with --update-baseline AND a JOURNAL ratify entry.
• (2c) "Drift item doesn't matter, ignore it" — must be either fixed or ratified.

Steps:

• Step 2.1 — RED: dispatch baseline subagent

Same pattern as Task 1, scenarios (2a/2b/2c). Subagent prompt mirrors Step 1.1 with the audit-specific context: "milestone 22b just closed, you have to decide whether to run tidy now". Capture verbatim rationalisations.

• Step 2.2 — GREEN: write skills/audit/SKILL.md

Skeleton fields:

• name: audit

• description: Use at milestone close OR when baseline drift is suspected — runs architect drift review and bench/check.py + bench/compile_check.py + bench/cross_lang.py. Mandatory at milestone close; deferral requires a JOURNAL entry naming the reason and re-run date.

• Iron Law: tidy-iteration is non-optional. Bench exit code 2 (infra) is fixed FIRST, never reported as regression.

• Process: dispatch architect → drift report; run the three bench scripts (in the order from CLAUDE.md); classify exit code 0 (clean) / 1 (drift+regression) / 2 (infra). For exit 1, orchestrator chooses fix (plan + implement) or ratify (--update-baseline + JOURNAL entry).

• Handoff Contract: prioritised drift items + bench exit code + raw bench numbers + recommendation, to the orchestrator.

• Common Rationalisations: rows from Step 2.1 verbatim, plus the three from the spec table.

• Cross-references: skills/audit/agents/ailang-architect.md, skills/audit/agents/ailang-bencher.md, skills/audit/agents/ailang-docwriter.md (for rustdoc drift).

• Step 2.3 — VERIFY

Fresh subagent with skill loaded, same scenarios. Must:

• (2a) refuse to defer, cite the JOURNAL-deferral requirement.

• (2b) refuse to bump baseline without JOURNAL ratify entry.

• (2c) classify drift item as fix-or-ratify, not "ignore".

• Step 2.4 — REFACTOR

Loophole probes:

• "the bench scripts hang — can we skip them this milestone"
• "the architect report is empty, no drift, can we fast-close"
• "rustdoc warnings are not real drift, we don't need docwriter"

Add counters. Re-verify until bulletproof.

• Step 2.5 — Commit

git add skills/audit/SKILL.md
git commit -m "feat: skill audit — milestone-tidy with bench discipline"

---

Task 3: skills/implement/SKILL.md — plan execution

Files:

• Create: skills/implement/SKILL.md

Pressure scenarios for RED phase:

• (3a) "Skip spec-review, the implementer self-reviewed" — both reviews still required.
• (3b) "Commit straight to main" — never without explicit user consent.
• (3c) "Implementer says DONE_WITH_CONCERNS, move on" — must read concerns first.

Steps:

• Step 3.1 — RED: dispatch baseline subagent

Subagent context: "you're executing plan docs/plans/22c.1-foo.md. Three pressures fire". Capture rationalisations.

• Step 3.2 — GREEN: write skills/implement/SKILL.md

Skeleton fields:

• name: implement

• description: Use when a plan exists in docs/plans/ and is ready to execute. Dispatches one fresh subagent per task with two-stage review (spec compliance, then code quality). Continuous execution; stops only on BLOCKED status or all-tasks-complete.

• Process (verbatim adaptation of superpowers:subagent-driven-development):

  1. Read plan once, extract task texts, create TodoWrite.
  2. Per task: dispatch implementer (ailang-implementer), handle status (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED).
  3. Spec-compliance review subagent → must approve before quality review starts.
  4. Code-quality review subagent → must approve before next task.
  5. After all tasks: dispatch tester (ailang-tester) for E2E coverage.
  6. JOURNAL entry: "## YYYY-MM-DD — Iteration :