[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6GXNB3WCMM2D14FR3HGF4NM":3,"skill-same:01M6GXNB3WCMM2D14FR3HGF4NM":81},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":37,"linkOnly":38,"markdownContent":39,"markdownBody":40,"frontMatter":41,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":54,"ownerHtmlUrl":55,"ownerBlogUrl":54,"ownerDescription":56,"updatedAt":57,"install":58,"resources":70},"01M6GXNB3WCMM2D14FR3HGF4NM","improve",null,"Autonomous quality improvement loop. Scores a target against a rubric, selects the highest-leverage axis, attacks it, verifies, documents, and loops. No pre-planning between iterations — each loop re-scores from scratch.","SethGammon\u002FCitadel","SethGammon","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F5523585?v=4","01M6GXJ90FD2CE9QF5GQERWN06","Seth Gammon","01M6GXJ94VXYGK5KAW14EYE901",931,"MIT","https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Fimprove\u002FSKILL.md",[],[5,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36],"leverage","improvement loop","true","quality improvement","re","attacks","loops","From Scratch","it","false","citadel","rubric","autonomous","quality","loop","planning","run","documents","2026-11-10 10:12:30",false,"---\nname: improve\nlicense: MIT\ndescription: >-\n  Autonomous quality improvement loop. Scores a target against a rubric, selects\n  the highest-leverage axis, attacks it, verifies, documents, and loops. No\n  pre-planning between iterations — each loop re-scores from scratch.\nuser-invocable: true\nauto-trigger: false\ntrigger_keywords:\n  - improve\n  - improvement loop\n  - quality loop\n  - rubric\n  - score against\n  - run improvement\n  - improve citadel\nlast-updated: 2026-03-28\n---\n\n# \u002Fimprove — Autonomous Quality Engine\n\n## Orientation\n\n**Use when:** Scoring a target against a rubric and iteratively improving it. Rubric required at `.planning\u002Frubrics\u002F{target}.md` (Phase 0 creates one if missing).\n\n**Don't use when:** Refactoring without a rubric (use `\u002Frefactor`), one-time code review (use `\u002Freview`), or debugging a specific bug (use `\u002Fsystematic-debugging`).\n\n## Invocation\n\n```\n\u002Fimprove {target}            # Loop until plateau or all axes >= 8.0\n\u002Fimprove {target} --n=3      # Run exactly N loops then stop\n\u002Fimprove {target} --axis={name}  # Force-attack a specific axis (skips scoring)\n\u002Fimprove {target} --score-only   # Score and report, no attack\n\u002Fimprove {target} --continue     # Resume from campaign state (used by daemon)\n\u002Fimprove citadel             # Targets Citadel itself\n```\n\n`target` is a slug that maps to `.planning\u002Frubrics\u002F{target}.md`.\nIf no rubric exists, run Phase 0 first.\n\n## Campaign Mode\n\nWhen invoked with `--n` or `--continue`, improve operates in **campaign mode** and maintains a campaign file that daemon can attach to.\n\n**Campaign file:** `.planning\u002Fcampaigns\u002Fimprove-{target}.md`, created automatically on the first invocation with `--n` (full template: docs\u002FQUALITY_LOOPS.md#campaign-file-template).\nFrontmatter: `version`, `id` (`improve-{target}-{ISO-date-slug}`), `status: active`, `type: improve`, `target`, `total_loops` ({n} or `unlimited`), `completed_loops: 0`, `current_level` (from rubric frontmatter), `estimated_cost_per_loop: 12`, `started`.\nBody: status and direction lines, a Loop History table (`Loop | Axis Attacked | Outcome | Score Movement`), and a Continuation State block (`next_loop`, `last_scorecard_log`, `last_outcome`, `phase_within_loop`, `level_up_triggered`).\n\n### Campaign lifecycle\n\nUpdate `phase_within_loop` at each phase: `scoring` → `selected-{axis}` → `attacking-{axis}` → `verifying` → `not-started`.\n\nOn loop complete: increment `completed_loops`, update `next_loop`\u002F`last_scorecard_log`\u002F`last_outcome`, append Loop History row.\n\n### The `--continue` flag\n\n1. Read `.planning\u002Fcampaigns\u002Fimprove-{target}.md` — error if missing or `status` not `active`\n2. If `completed_loops >= total_loops`: mark completed, exit\n3. If `phase_within_loop` is not `not-started`: restart current loop from Phase 1 (interrupted mid-loop)\n4. Load `last_scorecard_log` for delta comparison, then run Phase 1 onwards\n\n## Protocol\n\n### Phase 0: Rubric Bootstrap (one-time, requires human approval)\n\nRun only when `.planning\u002Frubrics\u002F{target}.md` does not exist.\n\n1. Read competitive research from `.planning\u002Fresearch\u002F` if available\n2. Spawn `\u002Fresearch --parallel` to survey comparable products if no research exists\n3. Draft 8-14 axes organized into 3-5 categories, each with:\n   - Weight (0.0–1.0), Category, three anchors (0\u002F5\u002F10), verification specs (programmatic\u002Fstructural\u002Fperceptual), research inputs\n4. Present draft rubric to the user with rationale for each axis\n5. **STOP. Do not proceed until the user approves the rubric.**\n   - If the AskUserQuestion tool is available, present the gate with it. Options: \"Approve as drafted\", \"Adjust axes\", \"Adjust weights\". On adjust: revise, re-present.\n   - If unavailable: ask as a plain text question and wait.\n   - Record the answer in the campaign file as `rubric_approved: {answer}`.\n6. Write approved rubric to `.planning\u002Frubrics\u002F{target}.md`\n\n### Phase 1: Score\n\nScore every axis in the rubric. No shortcuts. No cached scores from the previous loop.\n\n#### 1a. Programmatic checks (run first, in parallel)\n\nExecute the programmatic verification steps from the rubric. A programmatic failure caps that axis at 5 regardless of evaluator scores. Record raw results: which checks passed, which failed, what the failure was.\n\n#### 1b. Structural analysis\n\nExecute the structural checks from each axis's verification spec: file path existence, frontmatter schema consistency, benchmark coverage ratios, link rot, and cross-reference accuracy (check descriptions: docs\u002FQUALITY_LOOPS.md#structural-check-types).\n\n#### 1c. Perceptual scoring panel (three independent evaluators)\n\nSpawn three evaluator agents in parallel. Each receives the rubric with all axis definitions and anchors, read access to the target, its persona (A\u002FB\u002FC as defined in the rubric's Scoring Protocol), and the instruction to score every axis 0-10 with a one-sentence justification per axis (input list: docs\u002FQUALITY_LOOPS.md#evaluator-panel).\n\nEach evaluator scores independently. For each axis:\n- Final score = minimum of the three evaluators (plus programmatic cap if applicable)\n- If any two evaluators disagree by > 3 points: flag the axis as `needs-refinement`\n\n`needs-refinement` axes are logged but still scored. Do not halt on evaluator disagreement.\n\n#### 1d. Compile scorecard\n\nCompile a table with columns `Axis | A | B | C | Prog | Final | Delta | Flag` (layout: docs\u002FQUALITY_LOOPS.md#scorecard-format).\nFinal = min(A, B, C), then apply programmatic cap (sets Flag=cap). Delta = current − prior loop score (empty on loop 1).\n\n### Phase 2: Select\n\nChoose the single axis to attack this loop.\n\n**Selection formula:**\n```\nscore(axis) = (10 - current_score) × weight × effort_multiplier × recency_penalty\n```\n\n- `effort_multiplier`: low = 1.0, medium = 0.7, high = 0.4\n- `recency_penalty`: 0.5 if attacked in previous 2 loops, otherwise 1.0\n- Effort tiers: **low** \u003C 1hr, **medium** 1-3hrs, **high** 3+hrs\n\nIf `--axis` flag was set, skip selection and attack the specified axis.\n\nAnnounce the selection:\n```\nSelected: {axis_name} (score: {n}\u002F10, weight: {w}, effort: {e}, selection score: {s})\nRationale: {one sentence on why this axis now, not another}\n```\n\n### Phase 3: Attack\n\nExecute the improvement. Dispatch strategy depends on the axis category (expanded per-category playbooks: docs\u002FQUALITY_LOOPS.md#attack-dispatch-strategies).\n\n**ISOLATION MANDATE:** When dispatching to `\u002Fexperiment`, `\u002Ffleet`, or `\u002Fresearch --parallel`, always use the Agent tool with `isolation: \"worktree\"`. Sub-agents in worktrees get their own context windows; the orchestrator only receives their HANDOFF results.\n\n| Category | Dispatch | Verification |\n|---|---|---|\n| technical | `\u002Fexperiment` with before\u002Fafter comparison; speculative worktrees (Agent + isolation: \"worktree\") for approaches that might conflict | `node scripts\u002Frun-with-timeout.js 300 node scripts\u002Ftest-all.js` as the oracle |\n| documentation | direct: read current docs, fix specific gaps; cross-reference every claim against source | structural verification before committing |\n| experience | structural fixes + doc updates; run the actual install flow in a clean temp dir; inject synthetic failures per the programmatic spec | `\u002Fqa` |\n| positioning | `\u002Fresearch` to verify the competitive landscape is accurate, then update README\u002FFAQ\u002Fdemo copy | `\u002Fqa` confirms the updated page renders |\n| presentation | targeted changes per rubric anchors (no rewrites unless score is below 3) | `\u002Flive-preview` or `\u002Fqa` confirms visual changes render |\n| security | read the specific hooks\u002Fscripts involved, make targeted code changes | run the rubric's programmatic verification steps directly |\n\n**Artifact archiving:** when the attack tried multiple approaches, write a decision record to the loop log: `APPROACH COMPARISON: [approach A] vs [approach B] — winner: [A] because [reason]`.\n\n### Phase 4: Verify\n\nAfter the attack, re-score only the targeted axis (not full re-score).\n\nRun the four verification tiers from the rubric for the targeted axis:\n1. **Programmatic**: execute the specific checks, confirm they now pass\n2. **Structural**: verify the structural requirements are met\n3. **Perceptual**: spawn a single evaluator agent (Evaluator B — Newcomer) and score just the targeted axis\n4. **Behavioral simulation**: clone the repo into a temp directory and follow INSTALL.md exactly as written — no prior knowledge, no shortcuts. Measure whether each step completes without error and record wall time to first successful `\u002Fdo` command.\n   - Required when targeted axis is: `onboarding_friction`, `error_recovery`, `documentation_accuracy`, `command_discoverability`\n   - Optional for all other axes\n   - Result: `PASS {wall_time}` or `FAIL at step {n}: {what broke}`\n   - **A behavioral FAIL overrides a passing perceptual score.** Do not commit on behavioral FAIL.\n   - Skip only if the targeted axis could not plausibly affect the user path. Plausible = axis governs code shown\u002Fexecuted in the app, or controls presence\u002Fabsence of a UI element. Safe to skip: documentation axes (comments, docstrings), configuration-only axes, developer-tooling-only axes (e.g., `visual_coherence`, `api_surface_consistency`)\n\n**Regression check** (run on all axes, not just targeted):\n- Re-run programmatic checks on every axis that shares files with the changes\n- If any previously passing axis now fails programmatic: **abort, do not commit**\n- If perceptual estimate suggests any axis dropped > 0.5 from baseline: **abort, do not commit**\n\nOn abort: revert the changes, log the failure, treat as \"no improvement this loop\".\n\nOn pass: commit the changes with a descriptive message.\n\n### Phase 5: Document\n\nWrite the loop log. Always. Even on abort.\n\n**Log path:** `.planning\u002Fimprovement-logs\u002F{target}\u002Floop-{n}.md`\n\nRequired sections (full template: docs\u002FQUALITY_LOOPS.md#loop-log-template):\n- Header: date, loop number, selected axis, outcome (improved | no-change | aborted)\n- Scorecard: per-axis prior score, current score, delta\n- Attack summary: what was changed, approach (experiment \u002F direct \u002F research+update), files touched, plus the `APPROACH COMPARISON` record if multiple approaches were tried\n- Verification results: programmatic PASS\u002FFAIL, structural PASS\u002FFAIL, perceptual {score}\u002F10 with one-line rationale, behavioral `PASS {wall_time}` | `FAIL at step {n}: {reason}` | `SKIPPED`\n- Proposed axis additions: `PROPOSED AXIS: {name} | Rationale | Category | Weight | Anchors: 0=... 5=... 10=...` (or: None proposed this loop.)\n- What was learned: 2-3 sentences\n\nAll proposals go to `.planning\u002Frubrics\u002F{target}-proposals.md`. Never to the live rubric.\n\n### Phase 6: Loop or Exit\n\n**Exit conditions (check in order):**\n\n1. `--n` flag was set and N loops have completed: exit, report scorecard\n2. All axes >= 8.0: exit with \"target has reached quality ceiling\"\n3. No axis improved > 0.5 in either of the last 2 loops AND no programmatic cap is active AND at least 3 loops have completed: **trigger Level-Up Protocol**\n3a. A programmatic cap IS active AND the capped axis has not improved for 2 loops: **trigger Level-Up Protocol.** The cap is preventing score movement, not enforcing a ceiling — do not loop indefinitely.\n4. The user said stop: exit immediately\n\n**On Level-Up**: do not exit. Escalate. See Level-Up Protocol section.\n\n**On ceiling (all >= 8.0)**: report the final scorecard and recommend a Level-Up run.\n\n**On normal loop**: return to Phase 1. Re-score everything from scratch.\n\n**Campaign mode exit handling:**\n\n- **n-complete** (all loops done): set `status: completed`, move to `completed\u002F`\n- **ceiling** (all axes >= 8.0): set `status: completed`, move to `completed\u002F`\n- **level-up-triggered**: set `status: level-up-pending` (daemon will pause, not retry)\n- **aborted** (security failure, unrecoverable regression): set `status: parked`\n- **plateau** (no improvement, not yet level-up): set `status: parked` with reason\n- **user-stopped**: set `status: paused`\n\n### Level-Up Protocol\n\nTriggers when no axis improved > 0.5 in the last 2 consecutive loops, no programmatic cap is active, and at least 3 loops have completed.\n\n**Step 1: Freeze the snapshot**\n\nWrite `.planning\u002Frubrics\u002F{target}-level-{n}-final.md` with: date, loops completed, final scorecard, axes at ceiling (≥9.0 — their 10 anchors become Level {n+1}'s 5 anchors), and axes that plateaued below 9.0 with why.\n\n**Step 2: Write proposals**\n\nFor each axis: propose Level {n+1} re-anchoring (current 10 → new 5, propose new 10). For plateaued axes: re-anchor, replace with measurable proxy, or retire.\n\nAuto-include these three process axes if not already in the rubric: `decomposition_quality`, `scope_appropriateness`, `verification_depth`.\n\nWrite to `.planning\u002Frubrics\u002F{target}-proposals.md`: re-anchored axes (current 10 anchor, proposed 0\u002F5\u002F10), proposed new axes, axes proposed for retirement.\n\n**Step 3: Halt -- human approval required**\n\nDo not self-approve. Do not continue looping.\n\nIn campaign mode: set `status: level-up-pending`, set `level_up_triggered: true`, and write `awaiting: human approval of level-up proposals` to Continuation State.\n\nReport: what was achieved at this level (scorecard summary), the proposals file location, and what the expected new gains look like at the next level.\n\nThe loop resumes only when the human edits the live rubric with approved proposals\nand sets the campaign status back to `active`. Level {n+1} loops continue incrementing\nthe loop number (they do not reset to 1).\n\n**Step 4: Historical context for future evaluators**\n\nWhen the loop resumes after a level-up, every evaluator in Phase 1c receives the level-{n}-final.md snapshot as a reference baseline, plus the instruction: \"Scores from the previous level are the floor. A score of 5 at Level 2 means you have reached what was the ceiling at Level 1.\"\n\n## Fringe Cases\n\n- **No rubric**: run Phase 0, halt for human approval. Never improvise.\n- **Evaluators disagree > 3 pts**: log `needs-refinement`, use minimum score, continue.\n- **Programmatic checks can't be automated**: use structural + perceptual only, cap axis at 8.\n- **No improvement this loop**: document as \"no-change\", apply recency penalty.\n- **Loop 1 (no prior logs)**: delta fields empty — expected.\n- **Security axis fails programmatic**: halt and report. Blocking.\n- **`--continue` + no campaign file**: error, suggest `--n`.\n- **`--continue` + `level-up-pending`**: halt, point to proposals file, require human approval then `status: active`.\n- **`--continue` + `completed`**: do not resume, report final scorecard.\n- **`--n` + existing active campaign**: treat as `--continue`. If completed\u002Fparked: new campaign, incremented slug.\n\n## Quality Gates\n\n- Phase 0 requires human approval. No exceptions.\n- Phase 4 regression check must run. No committing without it.\n- Phase 4 behavioral simulation result must appear in the loop log for applicable axes. Behavioral FAIL blocks commit regardless of perceptual score.\n- Phase 5 loop log must be written. Even on abort, even on no-change.\n- Perceptual scoring: all three evaluators required for Phase 1. Single evaluator acceptable for Phase 4 spot-check only.\n- Selection formula must be shown in output.\n- Any axis with a programmatic failure is capped at 5. Cannot be overridden.\n- **The loop never writes to the live rubric.** Proposals go to `.planning\u002Frubrics\u002F{target}-proposals.md` only. Human approval required.\n- Level-Up Protocol requires human approval before resuming\n- **Campaign mode:** campaign file must be updated after every phase transition and every loop completion.\n- **Campaign mode:** level-up must set `status: level-up-pending`, not `parked` or `active`.\n\n## Contextual Gates\n\n**Disclosure:** State loop count, target, per-loop cost (~$12), total estimate. For `--continue`: loops remaining and spend so far. For unlimited: state exit conditions (plateau or all axes >= 8.0).\n\n**Reversibility:** Green = `--score-only` | Amber = standard loops (each commits separately) | Red = level-up (rewrites rubric anchors permanently). Red requires explicit confirmation.\n\n**Proportionality:** No rubric + no explicit request → suggest `\u002Freview`. All axes > 8.0 + `--n=1` → suggest `--axis`. Cost > $50 → confirm.\n\n**Trust gating:** Novice (0-4): `--score-only` \u002F `--n=1` only. Familiar (5-19): up to `--n=5`. Trusted (20+): no cap; confirm unlimited or cost > $50.\n\n## Exit Protocol\n\n```\n---HANDOFF---\n- Target: {target} — Loop {n} of {n_total or \"∞\"} — Level {current_level}\n- Outcome: {improved | plateau | ceiling | aborted | n-complete | level-up-triggered}\n- Score movement: {axis} {before} → {after} (+{delta})\n- Behavioral simulation: {PASS {wall_time} | FAIL | SKIPPED}\n- Proposed rubric additions: {count} — written to .planning\u002Frubrics\u002F{target}-proposals.md\n- Loop log: .planning\u002Fimprovement-logs\u002F{target}\u002Floop-{n}.md\n- Reversibility: amber -- each loop commits separately, revert individual loops with git revert\n- Next recommended axis: {axis_name} (if not exiting)\n- Level-up snapshot: .planning\u002Frubrics\u002F{target}-level-{n}-final.md (if level-up triggered)\n---\n```\n","# \u002Fimprove — Autonomous Quality Engine\n\n## Orientation\n\n**Use when:** Scoring a target against a rubric and iteratively improving it. Rubric required at `.planning\u002Frubrics\u002F{target}.md` (Phase 0 creates one if missing).\n\n**Don't use when:** Refactoring without a rubric (use `\u002Frefactor`), one-time code review (use `\u002Freview`), or debugging a specific bug (use `\u002Fsystematic-debugging`).\n\n## Invocation\n\n```\n\u002Fimprove {target}            # Loop until plateau or all axes >= 8.0\n\u002Fimprove {target} --n=3      # Run exactly N loops then stop\n\u002Fimprove {target} --axis={name}  # Force-attack a specific axis (skips scoring)\n\u002Fimprove {target} --score-only   # Score and report, no attack\n\u002Fimprove {target} --continue     # Resume from campaign state (used by daemon)\n\u002Fimprove citadel             # Targets Citadel itself\n```\n\n`target` is a slug that maps to `.planning\u002Frubrics\u002F{target}.md`.\nIf no rubric exists, run Phase 0 first.\n\n## Campaign Mode\n\nWhen invoked with `--n` or `--continue`, improve operates in **campaign mode** and maintains a campaign file that daemon can attach to.\n\n**Campaign file:** `.planning\u002Fcampaigns\u002Fimprove-{target}.md`, created automatically on the first invocation with `--n` (full template: docs\u002FQUALITY_LOOPS.md#campaign-file-template).\nFrontmatter: `version`, `id` (`improve-{target}-{ISO-date-slug}`), `status: active`, `type: improve`, `target`, `total_loops` ({n} or `unlimited`), `completed_loops: 0`, `current_level` (from rubric frontmatter), `estimated_cost_per_loop: 12`, `started`.\nBody: status and direction lines, a Loop History table (`Loop | Axis Attacked | Outcome | Score Movement`), and a Continuation State block (`next_loop`, `last_scorecard_log`, `last_outcome`, `phase_within_loop`, `level_up_triggered`).\n\n### Campaign lifecycle\n\nUpdate `phase_within_loop` at each phase: `scoring` → `selected-{axis}` → `attacking-{axis}` → `verifying` → `not-started`.\n\nOn loop complete: increment `completed_loops`, update `next_loop`\u002F`last_scorecard_log`\u002F`last_outcome`, append Loop History row.\n\n### The `--continue` flag\n\n1. Read `.planning\u002Fcampaigns\u002Fimprove-{target}.md` — error if missing or `status` not `active`\n2. If `completed_loops >= total_loops`: mark completed, exit\n3. If `phase_within_loop` is not `not-started`: restart current loop from Phase 1 (interrupted mid-loop)\n4. Load `last_scorecard_log` for delta comparison, then run Phase 1 onwards\n\n## Protocol\n\n### Phase 0: Rubric Bootstrap (one-time, requires human approval)\n\nRun only when `.planning\u002Frubrics\u002F{target}.md` does not exist.\n\n1. Read competitive research from `.planning\u002Fresearch\u002F` if available\n2. Spawn `\u002Fresearch --parallel` to survey comparable products if no research exists\n3. Draft 8-14 axes organized into 3-5 categories, each with:\n   - Weight (0.0–1.0), Category, three anchors (0\u002F5\u002F10), verification specs (programmatic\u002Fstructural\u002Fperceptual), research inputs\n4. Present draft rubric to the user with rationale for each axis\n5. **STOP. Do not proceed until the user approves the rubric.**\n   - If the AskUserQuestion tool is available, present the gate with it. Options: \"Approve as drafted\", \"Adjust axes\", \"Adjust weights\". On adjust: revise, re-present.\n   - If unavailable: ask as a plain text question and wait.\n   - Record the answer in the campaign file as `rubric_approved: {answer}`.\n6. Write approved rubric to `.planning\u002Frubrics\u002F{target}.md`\n\n### Phase 1: Score\n\nScore every axis in the rubric. No shortcuts. No cached scores from the previous loop.\n\n#### 1a. Programmatic checks (run first, in parallel)\n\nExecute the programmatic verification steps from the rubric. A programmatic failure caps that axis at 5 regardless of evaluator scores. Record raw results: which checks passed, which failed, what the failure was.\n\n#### 1b. Structural analysis\n\nExecute the structural checks from each axis's verification spec: file path existence, frontmatter schema consistency, benchmark coverage ratios, link rot, and cross-reference accuracy (check descriptions: docs\u002FQUALITY_LOOPS.md#structural-check-types).\n\n#### 1c. Perceptual scoring panel (three independent evaluators)\n\nSpawn three evaluator agents in parallel. Each receives the rubric with all axis definitions and anchors, read access to the target, its persona (A\u002FB\u002FC as defined in the rubric's Scoring Protocol), and the instruction to score every axis 0-10 with a one-sentence justification per axis (input list: docs\u002FQUALITY_LOOPS.md#evaluator-panel).\n\nEach evaluator scores independently. For each axis:\n- Final score = minimum of the three evaluators (plus programmatic cap if applicable)\n- If any two evaluators disagree by > 3 points: flag the axis as `needs-refinement`\n\n`needs-refinement` axes are logged but still scored. Do not halt on evaluator disagreement.\n\n#### 1d. Compile scorecard\n\nCompile a table with columns `Axis | A | B | C | Prog | Final | Delta | Flag` (layout: docs\u002FQUALITY_LOOPS.md#scorecard-format).\nFinal = min(A, B, C), then apply programmatic cap (sets Flag=cap). Delta = current − prior loop score (empty on loop 1).\n\n### Phase 2: Select\n\nChoose the single axis to attack this loop.\n\n**Selection formula:**\n```\nscore(axis) = (10 - current_score) × weight × effort_multiplier × recency_penalty\n```\n\n- `effort_multiplier`: low = 1.0, medium = 0.7, high = 0.4\n- `recency_penalty`: 0.5 if attacked in previous 2 loops, otherwise 1.0\n- Effort tiers: **low** \u003C 1hr, **medium** 1-3hrs, **high** 3+hrs\n\nIf `--axis` flag was set, skip selection and attack the specified axis.\n\nAnnounce the selection:\n```\nSelected: {axis_name} (score: {n}\u002F10, weight: {w}, effort: {e}, selection score: {s})\nRationale: {one sentence on why this axis now, not another}\n```\n\n### Phase 3: Attack\n\nExecute the improvement. Dispatch strategy depends on the axis category (expanded per-category playbooks: docs\u002FQUALITY_LOOPS.md#attack-dispatch-strategies).\n\n**ISOLATION MANDATE:** When dispatching to `\u002Fexperiment`, `\u002Ffleet`, or `\u002Fresearch --parallel`, always use the Agent tool with `isolation: \"worktree\"`. Sub-agents in worktrees get their own context windows; the orchestrator only receives their HANDOFF results.\n\n| Category | Dispatch | Verification |\n|---|---|---|\n| technical | `\u002Fexperiment` with before\u002Fafter comparison; speculative worktrees (Agent + isolation: \"worktree\") for approaches that might conflict | `node scripts\u002Frun-with-timeout.js 300 node scripts\u002Ftest-all.js` as the oracle |\n| documentation | direct: read current docs, fix specific gaps; cross-reference every claim against source | structural verification before committing |\n| experience | structural fixes + doc updates; run the actual install flow in a clean temp dir; inject synthetic failures per the programmatic spec | `\u002Fqa` |\n| positioning | `\u002Fresearch` to verify the competitive landscape is accurate, then update README\u002FFAQ\u002Fdemo copy | `\u002Fqa` confirms the updated page renders |\n| presentation | targeted changes per rubric anchors (no rewrites unless score is below 3) | `\u002Flive-preview` or `\u002Fqa` confirms visual changes render |\n| security | read the specific hooks\u002Fscripts involved, make targeted code changes | run the rubric's programmatic verification steps directly |\n\n**Artifact archiving:** when the attack tried multiple approaches, write a decision record to the loop log: `APPROACH COMPARISON: [approach A] vs [approach B] — winner: [A] because [reason]`.\n\n### Phase 4: Verify\n\nAfter the attack, re-score only the targeted axis (not full re-score).\n\nRun the four verification tiers from the rubric for the targeted axis:\n1. **Programmatic**: execute the specific checks, confirm they now pass\n2. **Structural**: verify the structural requirements are met\n3. **Perceptual**: spawn a single evaluator agent (Evaluator B — Newcomer) and score just the targeted axis\n4. **Behavioral simulation**: clone the repo into a temp directory and follow INSTALL.md exactly as written — no prior knowledge, no shortcuts. Measure whether each step completes without error and record wall time to first successful `\u002Fdo` command.\n   - Required when targeted axis is: `onboarding_friction`, `error_recovery`, `documentation_accuracy`, `command_discoverability`\n   - Optional for all other axes\n   - Result: `PASS {wall_time}` or `FAIL at step {n}: {what broke}`\n   - **A behavioral FAIL overrides a passing perceptual score.** Do not commit on behavioral FAIL.\n   - Skip only if the targeted axis could not plausibly affect the user path. Plausible = axis governs code shown\u002Fexecuted in the app, or controls presence\u002Fabsence of a UI element. Safe to skip: documentation axes (comments, docstrings), configuration-only axes, developer-tooling-only axes (e.g., `visual_coherence`, `api_surface_consistency`)\n\n**Regression check** (run on all axes, not just targeted):\n- Re-run programmatic checks on every axis that shares files with the changes\n- If any previously passing axis now fails programmatic: **abort, do not commit**\n- If perceptual estimate suggests any axis dropped > 0.5 from baseline: **abort, do not commit**\n\nOn abort: revert the changes, log the failure, treat as \"no improvement this loop\".\n\nOn pass: commit the changes with a descriptive message.\n\n### Phase 5: Document\n\nWrite the loop log. Always. Even on abort.\n\n**Log path:** `.planning\u002Fimprovement-logs\u002F{target}\u002Floop-{n}.md`\n\nRequired sections (full template: docs\u002FQUALITY_LOOPS.md#loop-log-template):\n- Header: date, loop number, selected axis, outcome (improved | no-change | aborted)\n- Scorecard: per-axis prior score, current score, delta\n- Attack summary: what was changed, approach (experiment \u002F direct \u002F research+update), files touched, plus the `APPROACH COMPARISON` record if multiple approaches were tried\n- Verification results: programmatic PASS\u002FFAIL, structural PASS\u002FFAIL, perceptual {score}\u002F10 with one-line rationale, behavioral `PASS {wall_time}` | `FAIL at step {n}: {reason}` | `SKIPPED`\n- Proposed axis additions: `PROPOSED AXIS: {name} | Rationale | Category | Weight | Anchors: 0=... 5=... 10=...` (or: None proposed this loop.)\n- What was learned: 2-3 sentences\n\nAll proposals go to `.planning\u002Frubrics\u002F{target}-proposals.md`. Never to the live rubric.\n\n### Phase 6: Loop or Exit\n\n**Exit conditions (check in order):**\n\n1. `--n` flag was set and N loops have completed: exit, report scorecard\n2. All axes >= 8.0: exit with \"target has reached quality ceiling\"\n3. No axis improved > 0.5 in either of the last 2 loops AND no programmatic cap is active AND at least 3 loops have completed: **trigger Level-Up Protocol**\n3a. A programmatic cap IS active AND the capped axis has not improved for 2 loops: **trigger Level-Up Protocol.** The cap is preventing score movement, not enforcing a ceiling — do not loop indefinitely.\n4. The user said stop: exit immediately\n\n**On Level-Up**: do not exit. Escalate. See Level-Up Protocol section.\n\n**On ceiling (all >= 8.0)**: report the final scorecard and recommend a Level-Up run.\n\n**On normal loop**: return to Phase 1. Re-score everything from scratch.\n\n**Campaign mode exit handling:**\n\n- **n-complete** (all loops done): set `status: completed`, move to `completed\u002F`\n- **ceiling** (all axes >= 8.0): set `status: completed`, move to `completed\u002F`\n- **level-up-triggered**: set `status: level-up-pending` (daemon will pause, not retry)\n- **aborted** (security failure, unrecoverable regression): set `status: parked`\n- **plateau** (no improvement, not yet level-up): set `status: parked` with reason\n- **user-stopped**: set `status: paused`\n\n### Level-Up Protocol\n\nTriggers when no axis improved > 0.5 in the last 2 consecutive loops, no programmatic cap is active, and at least 3 loops have completed.\n\n**Step 1: Freeze the snapshot**\n\nWrite `.planning\u002Frubrics\u002F{target}-level-{n}-final.md` with: date, loops completed, final scorecard, axes at ceiling (≥9.0 — their 10 anchors become Level {n+1}'s 5 anchors), and axes that plateaued below 9.0 with why.\n\n**Step 2: Write proposals**\n\nFor each axis: propose Level {n+1} re-anchoring (current 10 → new 5, propose new 10). For plateaued axes: re-anchor, replace with measurable proxy, or retire.\n\nAuto-include these three process axes if not already in the rubric: `decomposition_quality`, `scope_appropriateness`, `verification_depth`.\n\nWrite to `.planning\u002Frubrics\u002F{target}-proposals.md`: re-anchored axes (current 10 anchor, proposed 0\u002F5\u002F10), proposed new axes, axes proposed for retirement.\n\n**Step 3: Halt -- human approval required**\n\nDo not self-approve. Do not continue looping.\n\nIn campaign mode: set `status: level-up-pending`, set `level_up_triggered: true`, and write `awaiting: human approval of level-up proposals` to Continuation State.\n\nReport: what was achieved at this level (scorecard summary), the proposals file location, and what the expected new gains look like at the next level.\n\nThe loop resumes only when the human edits the live rubric with approved proposals\nand sets the campaign status back to `active`. Level {n+1} loops continue incrementing\nthe loop number (they do not reset to 1).\n\n**Step 4: Historical context for future evaluators**\n\nWhen the loop resumes after a level-up, every evaluator in Phase 1c receives the level-{n}-final.md snapshot as a reference baseline, plus the instruction: \"Scores from the previous level are the floor. A score of 5 at Level 2 means you have reached what was the ceiling at Level 1.\"\n\n## Fringe Cases\n\n- **No rubric**: run Phase 0, halt for human approval. Never improvise.\n- **Evaluators disagree > 3 pts**: log `needs-refinement`, use minimum score, continue.\n- **Programmatic checks can't be automated**: use structural + perceptual only, cap axis at 8.\n- **No improvement this loop**: document as \"no-change\", apply recency penalty.\n- **Loop 1 (no prior logs)**: delta fields empty — expected.\n- **Security axis fails programmatic**: halt and report. Blocking.\n- **`--continue` + no campaign file**: error, suggest `--n`.\n- **`--continue` + `level-up-pending`**: halt, point to proposals file, require human approval then `status: active`.\n- **`--continue` + `completed`**: do not resume, report final scorecard.\n- **`--n` + existing active campaign**: treat as `--continue`. If completed\u002Fparked: new campaign, incremented slug.\n\n## Quality Gates\n\n- Phase 0 requires human approval. No exceptions.\n- Phase 4 regression check must run. No committing without it.\n- Phase 4 behavioral simulation result must appear in the loop log for applicable axes. Behavioral FAIL blocks commit regardless of perceptual score.\n- Phase 5 loop log must be written. Even on abort, even on no-change.\n- Perceptual scoring: all three evaluators required for Phase 1. Single evaluator acceptable for Phase 4 spot-check only.\n- Selection formula must be shown in output.\n- Any axis with a programmatic failure is capped at 5. Cannot be overridden.\n- **The loop never writes to the live rubric.** Proposals go to `.planning\u002Frubrics\u002F{target}-proposals.md` only. Human approval required.\n- Level-Up Protocol requires human approval before resuming\n- **Campaign mode:** campaign file must be updated after every phase transition and every loop completion.\n- **Campaign mode:** level-up must set `status: level-up-pending`, not `parked` or `active`.\n\n## Contextual Gates\n\n**Disclosure:** State loop count, target, per-loop cost (~$12), total estimate. For `--continue`: loops remaining and spend so far. For unlimited: state exit conditions (plateau or all axes >= 8.0).\n\n**Reversibility:** Green = `--score-only` | Amber = standard loops (each commits separately) | Red = level-up (rewrites rubric anchors permanently). Red requires explicit confirmation.\n\n**Proportionality:** No rubric + no explicit request → suggest `\u002Freview`. All axes > 8.0 + `--n=1` → suggest `--axis`. Cost > $50 → confirm.\n\n**Trust gating:** Novice (0-4): `--score-only` \u002F `--n=1` only. Familiar (5-19): up to `--n=5`. Trusted (20+): no cap; confirm unlimited or cost > $50.\n\n## Exit Protocol\n\n```\n---HANDOFF---\n- Target: {target} — Loop {n} of {n_total or \"∞\"} — Level {current_level}\n- Outcome: {improved | plateau | ceiling | aborted | n-complete | level-up-triggered}\n- Score movement: {axis} {before} → {after} (+{delta})\n- Behavioral simulation: {PASS {wall_time} | FAIL | SKIPPED}\n- Proposed rubric additions: {count} — written to .planning\u002Frubrics\u002F{target}-proposals.md\n- Loop log: .planning\u002Fimprovement-logs\u002F{target}\u002Floop-{n}.md\n- Reversibility: amber -- each loop commits separately, revert individual loops with git revert\n- Next recommended axis: {axis_name} (if not exiting)\n- Level-up snapshot: .planning\u002Frubrics\u002F{target}-level-{n}-final.md (if level-up triggered)\n---\n```\n",{"name":5,"license":15,"description":7,"auto-trigger":38,"last-updated":42,"user-invocable":43,"trigger_keywords":44},1774656000000,true,[5,20,45,30,46,47,48],"quality loop","score against","run improvement","improve citadel","main","e1a3d45697a0f323aaedcbea0ab6a0387b5fe722","skills\u002Fimprove",84,"https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel","https:\u002F\u002Fsethgammon.github.io\u002FCitadel\u002F","https:\u002F\u002Fgithub.com\u002FSethGammon","Building Citadel, the repo-local operating layer for Claude Code and Codex. Persistent work, routing, verification, and coordinated agent fleets.","2026-11-13 02:05:13",{"source":8,"skillName":5,"commands":59,"prompt":69,"zipAvailable":43},[60,63,66],{"tool":61,"command":62},"npx","npx skills add SethGammon\u002FCitadel --skill improve",{"tool":64,"command":65},"bunx","bunx skills add SethGammon\u002FCitadel --skill improve",{"tool":67,"command":68},"pnpm","pnpm dlx skills add SethGammon\u002FCitadel --skill improve","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Fimprove\u002FSKILL.md",[71,77],{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"__benchmarks__\u002Fno-rubric.md","REFERENCE","参考文档",833,"https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Fimprove\u002F__benchmarks__\u002Fno-rubric.md",{"path":78,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":79,"sourceHtmlUrl":80},"__benchmarks__\u002Fscore-only.md",940,"https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Fimprove\u002F__benchmarks__\u002Fscore-only.md",[82,107,136,160,185,204],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":37},"01M6GXSBKE9A2HQWF8QRAZ4WJ5","workspace","Multi-repo campaign coordinator. Same lifecycle as fleet -- scope claims, discovery relay, wave-based execution -- but the unit of work is a repo, not a file. Coordinates campaigns across repositories with shared context.","https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Fworkspace\u002FSKILL.md",[],[84,89,90,91,92,93,94,95,96,97,98,99,100,28,101,102,103,104,105,106],"repos","snowflake","multi-repo","work","context","campaign","coordinate","but","across","campaigns","shared","as","scope","add","unit","coordinator","fleet","claims",{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":118,"publishedAt":37},"01M6GXS873AD1Y6RTM6GV47F3E","wiki","Markdown-first knowledge base where the LLM acts as librarian. Ingests raw sources, compiles and interlinks topic files, self-maintains an index. No vector DB or embeddings required -- uses LLM-native navigation over structured markdown up to ~400K words.","https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Fwiki\u002FSKILL.md",[113],{"categoryNo":114,"categoryName":115,"taxonomyType":116,"taxonomyTypeDesc":117},"01JBSEEDCAT000000000000021","资料检索与研究","SCENARIO","使用场景",[109,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,100,28,134,135],"vector","embeddings","librarian","markdown","knowledge","karpathy","knowledge management","karpathy wiki","up","files","maintain","self","knowledge base","project","db","sources","native",{"skillNo":137,"name":138,"nameZh":6,"description":139,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":140,"categories":141,"keywords":142,"publishedAt":37},"01M6GXS2840SJ61285SZ43EJC3","watch","File sentinel that monitors the working directory for changes and marker comments, then auto-triggers appropriate skills. Poll-based via git diff against the last scan commit. Writes intake items for batch processing and routes marker actions through \u002Fdo. Use for automatic reactions to file changes; do NOT use for one-off inspection or tasks needing human judgment per file.","https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Fwatch\u002FSKILL.md",[],[138,143,144,145,146,147,148,149,150,151,152,153,128,154,155,156,157,158,28,159],"directory","commit","tasks","git","batch","actions","start","sentinel","diff","auto","stop","do","scan","human","judgment","reactions","processing",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":169,"publishedAt":37},"01M6GXRXHYJ5RD9RZP81S2VFSW","verify","Self-test the Citadel hook pipeline from within a live session. Exercises real tool calls (Write, Edit, Bash, Read) and checks that hooks fired, telemetry accumulated, and no errors occurred. Reports HOOK HEALTH: PASS or HOOK HEALTH: FAIL with a per-hook breakdown.","https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Fverify\u002FSKILL.md",[166],{"categoryNo":167,"categoryName":168,"taxonomyType":116,"taxonomyTypeDesc":117},"01JBSEEDCAT000000000000008","测试与质量",[162,29,170,171,172,173,174,175,176,177,178,179,180,130,181,28,182,183,184,21],"telemetry","harness","pipeline","Bash","tool","read","write","edit","session","hooks","reports","live","hook","errors","calls",{"skillNo":186,"name":187,"nameZh":6,"description":188,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":189,"categories":190,"keywords":191,"publishedAt":37},"01M6GXRS9MCJFMQZ917H2XH3AC","unharness","Safely leave Citadel using the active adoption receipt. Produces a no-write, reviewable plan, preserves a portable archive, removes only exact owned material, and reports modified or externally registered surfaces as retained or unknown. Legacy installs must be imported before exact leave is claimed.","https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Funharness\u002FSKILL.md",[],[187,192,29,171,193,194,195,196,197,127,180,198,199,200,201,202,100,28,203,21],"uninstall","adoption","plan","archive","remove","only","Legacy","surfaces","clean","imported","active","material",{"skillNo":205,"name":206,"nameZh":6,"description":207,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":208,"categories":209,"keywords":218,"publishedAt":37},"01M6GXRMEJ2VHD43R9FNPD4910","triage","GitHub issue and PR investigator. Pulls open issues\u002FPRs, classifies them, searches the codebase for root cause or reviews contributed code, proposes fixes with file:line references, and optionally implements fixes. Use for investigating GitHub issues and reviewing PRs; do NOT use for general code review unrelated to GitHub issues.","https:\u002F\u002Fgithub.com\u002FSethGammon\u002FCitadel\u002Fblob\u002Fmain\u002Fskills\u002Ftriage\u002FSKILL.md",[210,213],{"categoryNo":211,"categoryName":212,"taxonomyType":116,"taxonomyTypeDesc":117},"01JBSEEDCAT000000000000007","代码审查",{"categoryNo":214,"categoryName":215,"taxonomyType":216,"taxonomyTypeDesc":217},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[206,219,220,221,222,223,224,225,226,227,228,229,230,231,154,28,232,233,234,21],"code review","review","review pr","pr","code","github issues","issues","open","use","unrelated","issue","general","references","line","investigator","reviews"]