# Authoring Rules

Bake every rule below into every authoring agent's prompt. These are
the non-negotiables that made the first run trustworthy; an agent
that skips one produces a skill that is worse than no skill.

## The Rules

1. **Audience**: a zero-context mid-level engineer or Sonnet-class
   model. Imperative runbook voice; copy-pasteable commands; every
   jargon term defined once; tables and checklists over prose. Each
   skill says when NOT to use it and which sibling to use instead.

2. **Format**: `.claude/skills/<name>/SKILL.md` with YAML
   frontmatter containing `name` and a trigger-rich `description`
   stating exactly when a model should load it.

3. **Ground truth only**: verify every command, flag, path, and
   claim against the repo before stating it. Wrong runbooks are
   worse than none. An unverified claim is a finding for the review
   phase, not a sentence in a skill.

4. **Embed knowledge**: do not reference private or user-specific
   paths as load-bearing sources. The skill must work for a reader
   who has only the repository.

5. **Date-stamp volatile facts**, and end each skill with a
   "Provenance and maintenance" section containing one-line
   re-verification commands for anything that may drift.

6. **No oversell**: unproven things stay labeled open or candidate.
   Nothing may contradict the project's own manifest or rules, and
   no skill may route around the project's change control.

7. **Write fence**: authoring agents write ONLY inside
   `.claude/skills/`. The rest of the repo is read-only. No
   mutating git commands.

## Per-Agent Prompt Template

Dispatch one agent per skill. Each prompt supplies:

```text
You are authoring one skill of a project skill library.

SKILL: <name from taxonomy>
CONTENTS: <the taxonomy row, expanded with Phase 1 findings>
DISCOVERY BRIEF: <the Phase 1 summary and the user's answers to
the five questions>

RULES (non-negotiable): <the seven rules above, verbatim>

Verify every claim against the repo before writing it. Return the
path of the SKILL.md you wrote plus a list of claims you could NOT
verify (these go to the review phase).
```

## Output Contract

Every authoring agent must return, in structure or prose:

- `path`: the SKILL.md written
- `verified_claims`: count of claims checked against the repo
- `unverified_claims`: list of claims stated as open or candidate
- `scripts_shipped`: any executables placed in the skill's
  `scripts/` dir

Agents without this contract get no output validation; treat a
missing contract as a review finding.

# Review Protocol

Run only after ALL skills exist. Authoring agents work in isolation
and cannot see each other's contradictions; the review phase is
where the library becomes one coherent artifact.

## Reviewers

Three parallel reviewers over the complete set, then one fixer.
Keep concurrency at three or fewer unless the dispatch was planned
and approved (see the repo's dispatch rules if it has them).

| Lens | Checks | Blocking when |
|------|--------|---------------|
| FACTUAL | Re-verify flags, paths, commands, and citations against the repo; run each skill's provenance one-liners. | A wrong command, nonexistent path, or invented claim would send an engineer down a wrong path. |
| DOCTRINE | Contradictions with the project's own rules or between skills; overstated claims; missing gating on anything that changes behavior. | Guidance routes around change control or two skills disagree on the same fact. |
| USABILITY | Trigger quality of descriptions; duplication (one home per fact, cross-references elsewhere); self-containedness; scannability. | A description would never fire, or a fact's only home is a private path. |

## Severity Ladder

- `blocking`: would send an engineer down a wrong path. Must be
  fixed before the mission reports done.
- `important`: misleading, drifted, or overstated. Fixed by the
  fixer in the same pass.
- `minor`: cosmetic. Recorded, not necessarily fixed.

## Reviewer Output Contract

```yaml
output_contract:
  required_sections: [summary, findings]
  finding_fields: [file, claim, evidence, severity, fix]
  min_evidence: command run plus output excerpt per finding
  strictness: strict
```

## Fixer

One agent, sequential, after all reviewers return:

- Applies blocking and important findings only.
- Re-verifies each finding before editing (re-run its evidence
  command); skips with a recorded reason if it does not reproduce.
- Same write fence as authoring: edits only inside
  `.claude/skills/`, no mutating git commands.
- Preserves each skill's voice, frontmatter validity, and the
  repo's markdown formatting rules.

## Why the Barrier Is Correct Here

The fixer needs ALL findings at once: duplicates across lenses must
be merged before editing, and a zero-finding review should skip the
fixer entirely. This is one of the few places a full barrier between
stages beats a pipeline.

## Final Report

The mission ends with a report to the user containing:

- [ ] The skill inventory with one-line descriptions
- [ ] What was verified by spot-check, with evidence references
- [ ] What remains uncertain, labeled open or candidate

# Skill Library Taxonomy

Sixteen categories, adapted to what Phase 1 discovery found. Merge
categories that are thin in the target repo, split ones that are
deep, and add domain categories the taxonomy does not imagine. Aim
for 10 to 16 skills total. Placeholders: `<project>` is the repo's
short name, `<domain>` is its technical field.

## Core Categories

Every project has these twelve.

| # | Skill | Contents |
|---|-------|----------|
| 1 | `<project>-change-control` | How changes are classified, gated, and reviewed here; the non-negotiables with the rationale and the historical incident behind each. |
| 2 | `<project>-debugging-playbook` | Symptom-to-triage table for this project's failure modes; the traps that cost real time, each with its story; discriminating experiments. |
| 3 | `<project>-failure-archaeology` | The chronicle: every major investigation, dead end, rejected fix, and revert, as symptom, root cause, evidence, and status, so no one re-fights a settled battle. Mine git history and docs hard. |
| 4 | `<project>-architecture-contract` | The load-bearing design decisions and why; the invariants that must hold; the known-weak points, stated plainly. |
| 5 | `<domain>-reference` | The domain-theory knowledge pack a mid-level person lacks: the field's math, protocols, and standards as they apply HERE, not a textbook. |
| 6 | `<project>-config-and-flags` | Catalog of every configuration axis: options, defaults, production vs experimental, guards; how to add one (checklist); re-verification commands, since flags drift. |
| 7 | `<project>-build-and-env` | Recreate the environment from scratch; known traps. |
| 8 | `<project>-run-and-operate` | Running and deploying the thing: command anatomy, data and artifact conventions, what output lands where. |
| 9 | `<project>-diagnostics-and-tooling` | How to MEASURE instead of eyeball: diagnostic tools with interpretation guides; ship real scripts in the skill's `scripts/` dir. |
| 10 | `<project>-validation-and-qa` | What counts as evidence here; acceptance-threshold discipline; the certified or golden inventory; how to add tests. |
| 11 | `<project>-docs-and-writing` | Maintaining the docs of record; templates; house style. |
| 12 | `<project>-external-positioning` | Papers, releases, ecosystem: what is novel vs known, what must be proven before claiming, reproducibility standards. |

## Advanced Categories

The layer that makes juniors dangerous, in the good way.

| # | Skill | Contents |
|---|-------|----------|
| 13 | `<project>-<hardest-problem>-campaign` | An executable, decision-gated campaign for the hardest live problem from Phase 1: numbered phases, exact commands, expected observations and numbers at every gate ("if you see X instead, branch to Y"), the solution menu ranked with theory obligations, known wrong paths fenced off, and a validation-and-promotion protocol that routes through change control. Success must be measurable, never judged by eye. |
| 14 | `<project>-proof-and-analysis-toolkit` | The first-principles analysis methods of this domain (whatever "prove it, don't just install it" means here), each as a recipe with a worked example from the repo's history. |
| 15 | `<project>-research-frontier` | Open problems where this project could advance the state of the art: why current approaches fail, this project's specific asset, the first three concrete steps IN THIS REPO, and a falsifiable "you have a result when" milestone. |
| 16 | `<project>-research-methodology` | The discipline that turns a hunch into an accepted result: the evidence bar (one mechanism must explain ALL observations including negatives, and survive assigned adversarial refutation), hypothesis-predicts-numbers-before-running, the idea lifecycle from experiment flag to adopted change or documented retirement, and where good ideas historically came from. |

## Adaptation Rules

- Merge when discovery finds a category thin: the first run in this
  repo folded run-and-operate, build tooling, and release steps into
  one `operations` skill because they shared a Makefile.
- Split when a category is deep enough to exceed one skill's token
  budget; prefer a hub skill plus modules over two overlapping
  skills.
- Add a `collective-memory` category when the project keeps memory in
  discussions, ADRs, or journals: searching memory before
  re-investigating is its own discipline.
- One home per fact. When two categories want the same fact, pick
  the owner and cross-reference from the other.

# Generalized Mission Prompt

The dispatch prompt below was distilled from the first successful
run of this mission (claude-night-market, 2026-07-02) and captured
on 2026-07-03. Paste it into a fresh session in the target
repository, or dispatch it through `/attune:skill-library`. It is
kept in one fenced block so it can be copied whole.

```text
You are a distinguished fellow on this project who is retiring.
Your final task: build a complete skill library under
`.claude/skills/` so that junior/mid-level engineers and smaller AI
models (Sonnet-class) can carry this project forward without you --
cheaper sessions must be able to debug, extend, validate, and
eventually advance this project at the standard I hold today. Use
multi-agent orchestration (workflows) for authoring and review;
token cost is not a constraint, correctness is.

## Phase 1 -- Discover before you write (no skill authoring yet)

Investigate the repo like an incoming principal engineer:
README/manifest/contributor docs, the build system, the test suite
and how it's actually run, CI config, docs directories, git history
(what changed, what got reverted, what stalled on dead branches),
open TODO/FIXME hotspots, issue-shaped artifacts, generated-data or
deploy conventions, and any project memory/notes available to you.
Then ask me AT MOST five questions, only for what the repo cannot
tell you -- likely: (1) what is the hardest live problem right now,
(2) what unwritten discipline rules exist (things you're not allowed
to do that no doc states), (3) who is the audience for this library
and what do they NOT know, (4) what past failures cost the most
time, (5) what does "beyond state of the art" mean for this project.
Fold my answers into everything below.

## Phase 2 -- Author the library (parallel agents, one skill per agent)

Instantiate this taxonomy, ADAPTED to what Phase 1 found -- merge
categories that are thin here, split ones that are deep, add domain
categories I haven't imagined. Aim for 10-16 skills:

CORE (every project has these):

1. <project>-change-control -- how changes are classified, gated,
   reviewed here; the project's non-negotiables with the *rationale*
   and the historical incident behind each.
2. <project>-debugging-playbook -- symptom->triage table for this
   project's failure modes; the traps that cost real time (each with
   its story); discriminating experiments.
3. <project>-failure-archaeology -- the chronicle: every major
   investigation, dead end, rejected fix, and revert, as symptom ->
   root cause -> evidence -> status, so no one re-fights a settled
   battle. Mine git history and docs hard for this.
4. <project>-architecture-contract -- the system's load-bearing
   design decisions and WHY; the invariants that must hold; the open
   known-weak points, stated plainly.
5. <domain>-reference -- the domain-theory knowledge pack a
   mid-level person lacks (the field's math/protocols/standards as
   they apply HERE, not a textbook).
6. <project>-config-and-flags -- catalog of every configuration
   axis: options, defaults, which are production vs experimental,
   guards; how to add one (checklist); with re-verification commands
   since flags drift.
7. <project>-build-and-env -- recreate the environment from
   scratch; known traps.
8. <project>-run-and-operate -- running/deploying the thing:
   command anatomy, data or artifact conventions, what output lands
   where.
9. <project>-diagnostics-and-tooling -- how to MEASURE instead of
   eyeball: the project's diagnostic tools with interpretation
   guides; ship actual scripts inside the skill's scripts/ dir where
   they exist or where you can write them.
10. <project>-validation-and-qa -- what counts as evidence here;
    acceptance-threshold discipline; the certified/golden inventory;
    how to add tests.
11. <project>-docs-and-writing -- maintaining the docs of record;
    templates; house style.
12. <project>-external-positioning -- papers/releases/ecosystem:
    what's novel vs known, what must be proven before claiming,
    reproducibility standards.

ADVANCED (the layer that makes juniors dangerous, in the good way):

13. <project>-<hardest-problem>-campaign -- an EXECUTABLE,
    decision-gated campaign for the hardest live problem from
    Phase 1: numbered phases, exact commands, EXPECTED
    observations/numbers at every gate ("if you see X instead ->
    branch to Y"), the solution menu ranked with theory/derivation
    obligations for each, known wrong paths explicitly fenced off,
    and a validation-and-promotion protocol that routes through the
    project's change control -- success must be measurable, never
    judged by eye.
14. <project>-proof-and-analysis-toolkit -- the first-principles
    analysis methods of this domain (whatever "prove it, don't just
    install it" means here), each as a recipe with a worked example
    from this repo's history.
15. <project>-research-frontier -- open problems where this project
    could advance the state of the art: for each, why current SOTA
    fails, this project's specific asset, the first three concrete
    steps IN THIS REPO, and a falsifiable "you have a result when..."
    milestone.
16. <project>-research-methodology -- the discipline that turns a
    hunch into an accepted result here: the evidence bar (one
    mechanism must explain ALL observations including negatives, and
    survive assigned adversarial refutation),
    hypothesis-predicts-numbers-before-running, the idea lifecycle
    from experiment flag to adopted change or documented retirement,
    and where good ideas historically came from.

AUTHORING RULES (bake into every agent's prompt):

- Audience: zero-context mid-level engineer or Sonnet-class model.
  Imperative runbook voice; copy-pasteable commands; every jargon
  term defined once; tables and checklists; each skill says when NOT
  to use it and which sibling to use instead.
- Format: `.claude/skills/<name>/SKILL.md`, YAML frontmatter with
  `name` and a trigger-rich `description` (exactly when a model
  should load it).
- GROUND TRUTH ONLY: verify every command, flag, path, and claim
  against the repo before stating it. Wrong runbooks are worse than
  none.
- Embed knowledge; don't reference private/user-specific paths as
  load-bearing sources.
- Date-stamp volatile facts; end each skill with a "Provenance and
  maintenance" section containing one-line re-verification commands
  for anything that may drift.
- No oversell: unproven things stay labeled open/candidate. Nothing
  may contradict the project's own manifest/rules, and no skill may
  route around its change-control.
- Write ONLY inside `.claude/skills/`; the rest of the repo is
  read-only; no mutating git commands.

## Phase 3 -- Review and fix (after ALL skills exist)

Three parallel reviewers over the complete set, then one fixer:

- FACTUAL: re-verify flags/paths/commands/citations against the
  repo; flag anything invented or stale (severity: would it send an
  engineer down a wrong path?).
- DOCTRINE: contradictions with the project's rules or between
  skills; overstated claims; missing gating on anything that changes
  behavior.
- USABILITY: trigger quality of descriptions, duplication (one home
  per fact, cross-references elsewhere), self-containedness,
  scannability.

Fixer applies blocking+important fixes. Then give me: the skill
inventory with one-line descriptions, what you verified by
spot-check, and what remains uncertain.
```

## Editorial Notes

- The prompt is preserved as dispatched, with three mechanical
  cleanups: invisible word-joiner characters removed from the
  numbered list, "contributordocs" split into two words, and a
  hyphenation typo fixed in "hypothesis-predicts-numbers".
- Session-specific directives from the original run (scope-guard
  override, branch choice) are intentionally NOT part of the
  template; record such directives in the mission state's
  `directive_overrides` instead.