@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/signal-community/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: signal-community
 description: "Check whether other people hit the same problem, via Stack Overflow and Hacker News (keyless) plus opt-in Reddit and X. Use when a bug report or complaint needs corroboration beyond one user. Advisory only: it belongs in a risks section, never in a business rule."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Community signal

package/pipeline/skills/shared/external/skill-creator/SKILL.md

@@ -1,49 +1,88 @@
 ---
 name: skill-creator
-description: "Author and refine skills for a plugin/toolkit efficiently. Use when creating a new skill, trimming or splitting an existing one, writing a skill's description, or choosing skill vs command vs agent vs CLAUDE.md. Encodes the house rules - lean SKILL.md as an index, progressive disclosure into bundled files, the reference (descriptive) vs workflow (imperative) split, no-prefix naming, and growing a skill from observed failures. Bundles a template, a pre-ship checklist, and good/bad description examples."
+description: "House guide for authoring plugin skills: creating a new skill, trimming or splitting a bloated one, writing or sharpening a description, and choosing between a skill, slash command, subagent, CLAUDE.md entry or MCP server. Covers the lean-index SKILL.md, progressive disclosure into bundled files, the reference vs workflow vs tool split, naming without a platform prefix, growing skills from observed failures, and the pre-ship audit. Ships templates, a checklist and description examples. Use for 'write a new skill', 'this skill is too long', 'improve this skill description', 'should this be a skill or an agent'. Not for writing the domain content itself, prompt writing unrelated to plugin skills, or per-session facts that belong in CLAUDE.md."
 user-invocable: true
-argument-hint: [new | trim | description]
+argument-hint: "[new | trim | description]"
 allowed-tools: Read, Write, Edit, Glob
 metadata:
   version: 1.0.0
+  source: multi-agent-pipeline
 ---
 
-# skill-creator - how to write skills here
-
-> **Layer:** reference (knowledge)
-> **Use when:** creating/trimming a skill, writing a description, or choosing skill vs command/agent/CLAUDE.md.
-> **Bundled (read on demand):** [template.md](template.md) · [checklist.md](checklist.md) · [examples.md](examples.md) · [label-check.md](label-check.md) · [audit.md](audit.md)
-
-## 1. Is a skill the right tool?
-- **CLAUDE.md** - broad facts/rules true *every* session.
-- **Skill** - on-demand procedure or knowledge for a recurring task.
-- **Subagent/agent** - needs independent reasoning + its own context/tools.
-- **MCP server** - structured integration with an external system's API.
-
-## 2. The description is discovery (the 90% lever)
-It's the *only* thing the model sees when deciding to load the skill. **Write it first.** Include **what + when + trigger words + one example trigger**, in third person. (Anthropic's data: vague→specific lifts activation ~20%→50%; adding examples ~72%→90%.) Good/bad pairs in [examples.md](examples.md).
-
-## 3. Keep it lean (it stays in context every turn once loaded)
-- `SKILL.md` is an **index** - aim for ~1 page, hard cap ~500 lines.
-- Push detail into bundled files **one level deep** (reference, examples, scripts). They cost zero tokens until read; nested-deeper files get partially read - don't nest.
-- A **script executes without its source entering context** - prefer a script over asking the model to regenerate code.
-- Challenge every line: *"would Claude err without this?"* If no, cut it.
-
-## 4. Pick the right degree of freedom (= our layers)
-- **reference skill → descriptive:** invariants, conventions + pointers to canonical files, decision heuristics, pitfalls, escape hatches. **No numbered procedures.**
-- **workflow skill → imperative spine:** a numbered procedure **only** for deterministic/irreversible steps (branch/PR, codegen, build/verify). Cite reference skills for the judgment.
-- **tool skill → thin index over a script/CLI:** lean SKILL.md (when + the run command + sub-commands at a glance), heavy detail in a bundled `reference.md`; the script is the engine (e.g. `tools/figma-utility`).
-
-## 5. Naming
-No platform prefix - the toolkit name + description already carry it. Reference = aspect noun (`navigation`); workflow = verb-phrase (`branch-and-pr`). Avoid vague/reserved (`helper`, `utils`, `claude-*`). For a name/title/strict-rule label that must carry its **whole intent**, validate it with the fresh-subagent inference test in [label-check.md](label-check.md) before committing.
-
-## 6. Grow it from real usage - don't pre-write
-1. Do the task **without** a skill; note where Claude actually fails.
-2. Write the **minimum** that fixes those gaps.
-3. Watch Claude use it: move reused detail up into SKILL.md, cut detail it ignores, sharpen the description if it didn't trigger.
-
-## Before shipping
-Start from [template.md](template.md); run [checklist.md](checklist.md). For a new or
-substantially-changed skill that must be trusted, run the **multi-architect audit**
-([audit.md](audit.md)) - a panel of distinct-lens reviewers + synthesis, looped
-fix → re-audit until no blockers/majors remain.
+# skill-creator - authoring plugin skills
+
+> **Layer:** knowledge (reference). **Use when:** creating, trimming, splitting, naming or describing a plugin skill, or gating one before it ships.
+> **Not for:** the domain content inside a skill (hand that to the domain skill), prompt writing unrelated to plugin skills, or facts every session needs (those go in CLAUDE.md).
+
+Bundled, read when the step needs it:
+
+- [template.md](template.md) - reference and workflow skeletons with frontmatter.
+- [checklist.md](checklist.md) - the pre-ship checklist.
+- [examples.md](examples.md) - weak and strong descriptions, wrong and right layer shapes.
+- [audit.md](audit.md) - the multi-architect audit loop and its lens sets; driven by `scripts/audit-panel.js`.
+- [label-check.md](label-check.md) - the fresh-subagent inference test for names and rule labels.
+
+## Arguments
+
+| Argument | Start at |
+|---|---|
+| `new` | Pick the artifact, write the description, then the template |
+| `trim` | Leanness and the cut test, then the checklist |
+| `description` | The description recipe and examples.md |
+
+## Pick the artifact first
+
+| Artifact | Holds |
+|---|---|
+| CLAUDE.md | facts and rules that are true in every session |
+| Skill | a procedure or body of knowledge for a recurring task, loaded on demand |
+| Subagent | work that needs its own reasoning, context window and tool set |
+| MCP server | a structured integration with an external API |
+
+## The description is the skill's only advertisement
+
+Before a skill loads, the model sees its name and description and nothing else. Write the description before the body. It needs:
+
+- **what** the skill covers or does, and **when** to use it;
+- concrete **trigger phrases** a user would actually type, plus one sample request;
+- the **platform** where it matters (iOS/SwiftUI, Compose, backend);
+- an implied **boundary** against sibling skills;
+- third person throughout.
+
+Anthropic's measurements: a specific description instead of a vague one lifted activation from about 20% to about 50%; adding examples took it from about 72% to about 90%. A one-liner with no when, no triggers and no platform gives the router nothing to match. See examples.md.
+
+## Keep SKILL.md an index
+
+- Everything in SKILL.md sits in context for every turn after it loads. Aim for about one page; 500 lines is the hard ceiling.
+- Push detail into bundled files **one level below** SKILL.md (reference, examples, scripts). They cost nothing until read. A file reached only through another bundled file tends to be read in part, so do not nest.
+- Deterministic work belongs in a script. Running it keeps its source out of context; never ask the model to write that code again each time.
+- **Cut test:** keep a line only if Claude would get the task wrong without it. Do not explain what the model already knows: a paragraph on how PDFs are structured loses to "use pdfplumber".
+
+## Layer sets the degrees of freedom
+
+| Layer | Voice | Contains | Never contains |
+|---|---|---|---|
+| reference | descriptive | invariants, conventions pointing at canonical files, decision heuristics, pitfalls, escape hatches | numbered procedures |
+| workflow | imperative | numbered steps only for deterministic or irreversible actions (branch and PR, codegen, build and verify), citations of reference skills for judgement, a verification gate | open-ended judgement dressed as steps |
+| tool | index | when to use, the run command, a sub-command overview; heavy detail in a bundled `reference.md`; the script is the engine | the engine's logic in prose |
+
+`tools/figma-utility` in the iOS toolkit is the model tool skill.
+
+## Naming
+
+- No platform prefix: the toolkit name and the description already say it.
+- Reference skills take an aspect noun (`navigation`); workflow skills a verb phrase (`branch-and-pr`).
+- Avoid vague or reserved names: `helper`, `utils`, anything starting with `claude-`.
+- When a name, title or strict-rule label has to carry its whole intent, run the label check before committing to it.
+
+## Grow skills from failures
+
+1. Do the task with no skill and note exactly where Claude goes wrong.
+2. Write the smallest skill that fixes those failures. Nothing speculative.
+3. Watch real use: promote detail that keeps getting read into SKILL.md, cut what is ignored, and sharpen the description whenever the skill failed to trigger.
+
+## Before it ships
+
+1. Run checklist.md as the self-review floor.
+2. New or substantially changed skill: run the audit loop in audit.md until `clearsBar` is true.
+3. Wire it: add the path to the `skills` array in `<plugin>/.claude-plugin/plugin.json`, bump the plugin version in `.github/plugin/marketplace.json`, and add a row to the plugin's `index` skill route table.

package/pipeline/skills/shared/external/skill-creator/audit.md

@@ -1,59 +1,63 @@
-# Multi-architect audit - adversarial quality gate for a skill
-
-The [checklist](checklist.md) is the self-review floor. This is the **high-confidence
-gate**: a panel of N independent reviewers, each a *distinct lens*, reads the skill
-against the rubric + ground truth, then a synthesizer dedups and rules. You **loop
-fix → re-audit until it passes** (no blockers/majors). Run it before shipping a new
-or substantially-changed skill, or whenever a skill must be trusted.
-
-Use the [Workflow tool](scripts/audit-panel.js) to fan the panel out - it returns
-`{remaining, clearsBar, verdict}`.
-
-## The loop (run to convergence)
-1. **Panel** - N agents, one lens each, read-only. Each returns specific findings
-   (severity · file:location · problem · concrete fix). Empty if its lens is clean.
-2. **Synthesize** - dedup overlaps; **drop false positives** (verify each against the
-   real files/repo before keeping); classify blocker / major / minor / nit;
-   `clearsBar = no blockers and no majors remain`.
-3. **If not clean** - apply the do-now set (blockers + majors + cheap high-value
-   minors), then run a **fresh** panel (see "Fresh each round") and repeat.
-4. **Stop** when `clearsBar` is true. The later/nit list is optional polish.
-
-## Rules that make it trustworthy
-- **Fresh panel each round.** After a fix, re-run the panel anew so agents read the
-  *current* files - do not reuse a prior run's cached results (they reflect the old
-  state and will report fixed issues as open / miss regressions).
-- **Verify before keeping.** Every finding must be confirmed against the actual file
-  or repo. The synthesizer drops anything it can't reproduce. Prefer findings that
-  cite a line and a reproduction.
-- **Ground-truth, not vibes.** Give the panel the rubric ([SKILL.md](SKILL.md) +
-  [checklist.md](checklist.md)), an exemplar skill, and the real source the skill
-  describes (e.g. the iOS repo). Agents read; they don't assume.
-- **Watch for regressions.** A fix can break something - the red-team lens and the
-  fresh re-audit exist to catch it (e.g. a broadened check that now false-positives).
-- **clearsBar gates the merge.** Don't merge with an open blocker/major.
-
-## Lenses - pick the set for the task
-One distinct lens per agent (+ a synthesizer). Two ready-made sets:
-
-**General skill audit** - discovery · leanness · shape/layer · scripts · accuracy-vs-source · domain-correctness · wiring · boundaries · red-team → synthesis.
-
-**Prompt-engineering audit** (when the concern is *prompt quality* - descriptions,
-instructions, triggering):
-1. **description-as-discovery** - what + when + trigger words + example; would it activate on a real task?
-2. **disambiguation** - distinct from siblings; a reader can tell when to pick this vs a neighbor.
-3. **trigger coverage** - the real user phrasings (and synonyms) are covered.
-4. **instruction clarity** - steps are unambiguous, ordered, single-interpretation; no vague directives.
-5. **degrees of freedom / layer fit** - reference=descriptive (no numbered procedure), workflow=spine, tool=thin-index; freedom matches the task.
-6. **progressive disclosure / leanness** - SKILL.md is an index; detail bundled one level deep; no duplication.
-7. **token efficiency** - every line is load-bearing; nothing restates what the model already knows.
-8. **consistency** - terminology, naming, paths, cross-references, examples all agree.
-9. **anti-patterns / misfire** - would the model over-apply it, skip a gate, hallucinate a path, or follow it into a wrong output?
-10. **red-team** - adversarially try to make it not trigger, trigger wrongly, or produce broken output; hunt overclaims (says X, the script doesn't).
-
-Scale the panel to risk: a quick check is ~3 lenses; a thorough gate is ~10.
-
-## Scope of fixes per round
-Fix **blockers + majors** always; fold in **cheap, high-value minors** while you're
-in the file. Defer speculative nits and pre-existing/out-of-scope drift to the
-"later" list (and `log()`/note them - don't silently drop coverage).
+# Multi-architect audit
+
+The checklist is what one author catches alone. The audit adds a panel of independent, read-only reviewers, each looking through one lens, and a synthesizer that turns their output into a decision. New skills and substantial changes go through it before merge.
+
+## The loop
+
+1. **Panel.** Every lens reviews the skill and returns findings, each with a severity, a `file:location`, the problem and a concrete fix. A clean lens returns an empty list.
+2. **Synthesis.** One agent merges duplicates, opens the real files to discard false positives, classifies the rest as blocker, major, minor or nit, and sets `clearsBar` to true only when no blocker and no major is left.
+3. **Fix.** If the bar is not cleared, apply the do-now set and start a **new** panel.
+4. **Stop** once `clearsBar` is true. Remaining nits are optional polish.
+
+### What to fix in a round
+
+- Always: every blocker and every major.
+- Also, when cheap and clearly valuable: minors.
+- Later, on a written list: speculative nits and drift that was already there or sits outside this change. Record them; never drop them silently.
+
+## Rules that keep the result trustworthy
+
+- **Fresh panel every round.** Cached results describe the files as they were; a resumed run audits the old version.
+- **Verify before keeping.** Each finding is checked against the file before it counts. Prefer findings that cite a line and a way to reproduce.
+- **Give the panel ground truth:** the rubric (skill-creator SKILL.md plus checklist.md), an exemplar skill of the same layer, and the actual source the skill describes.
+- **Watch the fixes.** A fix can break something else. The red-team lens and the fresh re-audit are there to catch that.
+- **`clearsBar` gates the merge.**
+
+## Lens sets
+
+Scale the panel to the risk: about three lenses for a quick check, about ten for a full gate.
+
+### General
+
+discovery, leanness, shape and layer, scripts, accuracy against the source, domain correctness, wiring, boundaries, red team, then synthesis.
+
+### Prompt engineering (the script's default ten)
+
+| Lens | Asks |
+|---|---|
+| discovery | Does the description alone get the skill loaded? |
+| disambiguation | Could it be confused with a sibling? |
+| triggers | Which real phrasings and synonyms are missing? |
+| clarity | Is every instruction unambiguous and actionable? |
+| layer | Does the degree of freedom fit the declared layer? |
+| leanness | Is SKILL.md an index with detail one level down? |
+| tokens | Which lines fail the cut test? |
+| consistency | Do terms, names, paths, cross-references and examples agree? |
+| misfire | Where would it over-apply, skip its gate, invent a path, or produce the wrong output? |
+| redteam | Make it fail to trigger, trigger wrongly, or break its output; find prose that claims what the script does not do. |
+
+## Running it with the script
+
+`scripts/audit-panel.js` is a Workflow-tool template (workflow name `skill-audit-panel`, phases Audit and Synthesis). It takes no arguments; edit its config block first:
+
+| Constant | Set to |
+|---|---|
+| `TARGET` | absolute paths of the SKILL.md and each bundled file and script |
+| `RUBRIC` | path to skill-creator's SKILL.md plus checklist.md |
+| `EXEMPLAR` | a known-good skill of the same layer |
+| `GROUND_TRUTH` | the real source the skill documents, with the key facts to check |
+| `LENSES` | label and brief pairs; defaults to the ten above |
+
+It runs one agent per lens in parallel (labelled `audit:<lens>`), tags each finding with its lens, and hands them all to a `synthesis` agent. The result is `{ remaining, clearsBar, verdict }`: the surviving findings with the lenses that raised them, the gate boolean, and a one-paragraph verdict.
+
+After applying fixes, launch it again as a new run. Do not resume the old one; resumed agents return cached results.

package/pipeline/skills/shared/external/skill-creator/checklist.md

@@ -1,32 +1,40 @@
 # Pre-ship checklist
 
-Run before considering a skill done.
+The floor for every skill. New or substantially changed skills also go through the audit loop in audit.md.
 
 ## Discovery
-- [ ] `description` says **what + when + trigger words**, third person, and names the platform (iOS/SwiftUI).
-- [ ] Description disambiguates from sibling skills (a reader can tell when to pick this vs a neighbor).
-- [ ] Tested: in a fresh task that should trigger it, does the model actually reach for it? If not, sharpen the description.
+
+- [ ] The description says what the skill does, when to use it, and lists trigger phrases, in third person.
+- [ ] It names the platform where that matters.
+- [ ] It separates this skill from its siblings.
+- [ ] Tried on a new task it ought to catch, the skill really fires.
 
 ## Leanness
-- [ ] `SKILL.md` reads like an index, ~1 page (hard cap ~500 lines).
-- [ ] Detail lives in bundled files **one level deep** - no nested-deeper references.
-- [ ] Every line survives "would Claude err without this?" - no over-explaining, no restating what the model knows.
-- [ ] Deterministic code is a **script**, not prose asking the model to regenerate it.
+
+- [ ] SKILL.md is roughly one page and works as an index, far below the 500-line cap.
+- [ ] Detail lives in bundled files exactly one level below SKILL.md.
+- [ ] Every line passes the cut test.
+- [ ] Anything deterministic ships as a script instead of prose the model must re-derive.
 
 ## Shape
-- [ ] Layer is explicit (reference or workflow) and matches the content.
-- [ ] **Reference** skill has **no numbered procedures** - heuristics + pointers only.
-- [ ] **Workflow** skill's numbered steps are **only** the deterministic/irreversible spine, and it has a **verification gate**.
-- [ ] Conventions **point to canonical files** rather than pasting code that will rot.
 
-## Naming & wiring
-- [ ] Name has **no platform prefix**; reference = aspect noun, workflow = verb-phrase; not vague/reserved.
-- [ ] Registered in the plugin manifest (`<plugin>/.claude-plugin/plugin.json` `skills` array) and the marketplace version bumped (`.github/plugin/marketplace.json`).
-- [ ] Listed in the `index` skill's route table.
+- [ ] The layer is declared and the content matches it.
+- [ ] Numbered procedures never appear in a reference skill.
+- [ ] A workflow skill's steps are only the deterministic spine, and it ends in a verification gate.
+- [ ] Conventions point at canonical files instead of pasting code that will go stale.
+
+## Naming and wiring
+
+- [ ] No platform prefix; noun for reference, verb phrase for workflow; not vague, not reserved.
+- [ ] Registered in the `skills` array of `<plugin>/.claude-plugin/plugin.json`.
+- [ ] Plugin version bumped in `.github/plugin/marketplace.json`.
+- [ ] A row in the plugin's `index` skill route table.
 
 ## House rules
-- [ ] No AI/Claude/Anthropic attribution anywhere in the skill or its examples.
-- [ ] Escape hatches name the skill to hand off to when this one doesn't apply.
 
-## High-confidence gate (new / substantially-changed skills)
-- [ ] Ran the multi-architect audit ([audit.md](audit.md)) and looped fix → re-audit until `clearsBar` (no blockers/majors).
+- [ ] Neither the skill nor its examples carry AI, Claude or Anthropic attribution.
+- [ ] Each escape hatch says which skill takes over.
+
+## Confidence gate
+
+- [ ] New or substantially changed: the multi-architect audit ran, fixes were applied, and a fresh panel returned `clearsBar: true`.

package/pipeline/skills/shared/external/skill-creator/examples.md

@@ -1,65 +1,65 @@
-# Examples - descriptions & shape
+# Examples
 
-## Descriptions: the discovery lever
+## Descriptions
+
+### Weak
 
-**Bad (vague - rarely triggers):**
 ```yaml
-description: Helps with navigation
+description: Helps with navigation stuff.
 ```
-Why it fails: no "when", no trigger words, no platform - the router can't tell what task this matches.
 
-**Good (what + when + triggers + platform):**
+No situation, no trigger words, no platform. The router has nothing to match a request against, so the skill stays unloaded.
+
+### Strong, reference layer
+
 ```yaml
-description: "In-app navigation for a SwiftUI iOS app - the coordinator-per-domain pattern, the tab shell, cross-domain navigation, deep links, and modals. Reach for this when adding a screen, a tab, a deep link, or a modal, or deciding how one screen reaches another."
+description: "Navigation for iOS / SwiftUI: NavigationStack paths, tab structure, deep links, sheets and full-screen modals, and where routing state lives. Use when adding a screen, a tab or a deep link, presenting a modal, or debugging a push that does nothing. Triggers: 'add a new screen', 'open this from a deep link', 'present as a sheet'."
 ```
-Why it works: states the domain, lists concrete triggers ("adding a screen, a tab, a deep link"), names the platform, and implies the boundary.
 
-**Workflow example (action + when to run):**
+Coverage, concrete situations, the platform, and quoted phrases a developer would type. The domain words keep it apart from sibling skills on state or overlays.
+
+### Strong, workflow layer
+
 ```yaml
-description: "Branch, commit, push, and open a PR for this repo. Owns the git/PR spine and house guardrails - type-first branch names, no AI attribution, no force-push, correct base branch. Reach for this whenever a change is ready to ship."
+description: "Creates a branch, commits, pushes and opens a pull request with the house guardrails: type-first branch names, conventional commit messages with no AI attribution, never a force push, and the correct base branch. Use when work is ready to ship. Triggers: 'open a PR', 'commit and push this', 'create a branch for this ticket'."
 ```
 
-### Recipe
-`<what it covers/does> + <concrete when/trigger phrases> + <platform> + <implied boundary vs siblings>`
+States the action, the guardrails that make it safe, when it applies, and how users ask for it.
 
----
+## Layer shape
 
-## Shape: reference vs workflow
+### Wrong: a reference skill written as keystrokes
 
-**Wrong - a reference skill drifting into a procedure:**
 ```markdown
-## Procedures
-1. Open the file
-2. Add the wrapper
-3. Register the route
-4. Build and run
+## Adding a tab
+1. Open AppTabView.swift.
+2. Add a case to the Tab enum.
+3. Add a .tabItem block under the last one.
+4. Build.
 ```
-A reference (knowledge) skill should describe *the rule and where the canonical example lives*, not script the keystrokes.
 
-**Right - reference stays descriptive:**
+A reference skill describes; it does not dictate. These steps go stale the first time the file changes.
+
+### Right: the rule plus where to look
+
 ```markdown
-## Decision rules
-- New screen in a domain → add `<Name>Screen` under its Presentation layer,
-  wrap content in the domain's container, route via the domain coordinator.
-  Canonical: `<repo>/Features/Profile/ProfileScreen.swift`.
+## Conventions
+- Tabs are cases of the root `Tab` enum; each case owns its own navigation path.
+  Canonical file: `App/Sources/AppTabView.swift`.
 ```
 
-**Right - workflow earns its numbered steps** (deterministic/irreversible spine):
+### Right: a workflow that earns its steps
+
 ```markdown
 ## Procedures
-1. Pre-flight: `git status` clean? on base branch?
-2. Branch: `git checkout -b <type>/<scope>/<desc>`
-3. Commit: stage; conventional message; strip any AI co-author trailer.
-4. Push; never force-push a protected branch.
-5. PR: `gh pr create --base <base> ...` (no AI footer).
+1. Pre-flight: `git status` is clean and the base branch is correct.
+2. Create `{type}/{scope}-{short-description}`.
+3. Commit with a conventional message; strip any AI co-author trailer.
+4. Push without `--force`; never to a protected branch.
+5. `gh pr create --base {base}` with no AI footer in the body.
+
 ## Verification
-- `git log -1` shows clean message, no AI trailer, correct author.
+- `git log -1` shows a clean message, no AI trailer, and the expected author.
 ```
 
----
-
-## Leanness: cut what the model already knows
-
-**Bloat:** "PDF files are documents that contain text and images. To read them you first need a library that can parse the binary format..."
-
-**Lean:** "Extract text from PDFs with `pdfplumber`."
+Every step is deterministic or irreversible, and the skill proves its result before it finishes.

package/pipeline/skills/shared/external/skill-creator/label-check.md

@@ -1,43 +1,55 @@
-# Label intent check - does a title carry its own meaning?
+# Label check
 
-A label (rule title, section header, principle/constraint name) is the handle a reader grasps *before* the body. If the handle leaks the wrong shape - ambiguous, one-sided, or off-topic - the reader forms the wrong model and the body has to fight it. This is a cheap test that catches that early: have **fresh subagents infer the rule from the label alone**, then compare against your intended meaning. Convergence = the label is self-carrying.
+A reader forms a model of a rule from its label before reading the body. If the label points the wrong way (ambiguous, covering only one side, or about something adjacent), that wrong model sticks. This test measures what a label actually conveys by asking agents that never see the body.
 
 ## When to run it
-- Naming a **strict rule** or constraint inside a skill (the kind a reader must obey).
-- A **section header** that gates non-trivial content (phase/principle/constraint names).
-- Any label meant to convey the **whole intent** of its body (not a summary - the intent).
-- Skip it for purely organizational labels ("Examples", "See also") - they carry no intent.
-
-## Inputs (collect first)
-1. **Candidate label** - the exact string under test.
-2. **Surrounding context** - one paragraph: which skill/doc, what adjacent labels cover, the domain concepts in play.
-3. **Intended meaning** - 1-3 sentences of ground truth (what the body says / what the reader should walk away believing). **Not** shown to the inference agents. If you can't state it in 3 sentences, the body is unclear - fix that first.
-
-## Procedure
-**One iteration = 5 parallel subagents**, each given ONLY the label + context (never the body), each forced to commit:
-```
-Context: <surrounding context - 1 paragraph>.
-The label under test is: **"<candidate label>"**
-You have NOT seen the body. From ONLY this label + context, what do you infer it
-enforces / requires / means? 1-2 concrete sentences, under 80 words. Commit - no
-hedging, no clarifying questions.
-```
-Launch all 5 in the **same** message (parallel) so they're independent by construction.
-
-**Convergence (per iteration), comparing the 5 inferences to the intended meaning:**
-- **PASS** - ≥4/5 cover *all* key intent beats (including the bidirectional / edge / scope beat, if the intent has one). Wording drift is fine.
-- **PARTIAL** - they consistently catch one side of a bidirectional rule but miss the other, or over-extend into an adjacent concern. Revise the label, re-run.
-- **FAIL** - inferences diverge wildly or miss the core beat. Revise, re-run.
-
-**Idempotency (after a PASS):** run **2 more rounds**, 5 fresh agents each (3×5 = 15 inferences), same prompt. Require **all 3 rounds PASS** with no new systematic miss - confirms the PASS wasn't luck. A regression in round 2/3 → treat as PARTIAL and iterate.
-
-**Termination:** converged (3/3 PASS) → apply the label. 3 iterations without a PASS → stop, hand back the best candidate + the persistent miss; don't force a label that won't stick.
+
+- Names of strict rules and constraints.
+- Section headers that gate non-trivial content.
+- Any label that is meant to carry the whole intent on its own, including top-level skill names.
+
+Purely organisational headers ("Examples", "Setup") do not need it.
+
+## Inputs
+
+1. The candidate label.
+2. One paragraph of the surrounding context, as a reader would meet it.
+3. The intended meaning in one to three sentences. This stays with you; the agents never see it. If you cannot state it in three sentences, fix the body before testing the label.
+
+## A round
+
+Launch five subagents **in one message**, so none anchors on another. Each receives only the label and the context paragraph, never the body, and is told to commit to what the label means in one or two sentences, under 80 words, with no hedging and no questions back.
+
+## Grading
+
+| Grade | Condition | Next |
+|---|---|---|
+| PASS | At least 4 of 5 inferences cover every key beat of the intent, including the bidirectional, edge or scope beat. Different wording is fine. | Idempotency rounds |
+| PARTIAL | The inferences consistently catch one side of a two-sided rule, or stretch into a neighbouring concern. | Revise, run again |
+| FAIL | Inferences diverge, or miss the core beat. | Revise, run again |
+
+## Idempotency
+
+After a first PASS, run two more rounds with five fresh agents each: 15 inferences in total. All three rounds must pass with no new systematic miss. A later round that regresses counts as PARTIAL.
+
+## Stopping
+
+- Three of three rounds pass: apply the label.
+- Three revisions without a PASS: stop, and hand back the best candidate together with the miss that kept recurring.
 
 ## Defaults
-5 agents/round · 3 rounds · 80-word inference cap · max 3 iterations before handing back. High-stakes labels (top-level skill names, protocol names) → 7 agents × 3 rounds; throwaway section headers → 3 × 2.
+
+| Stakes | Agents | Rounds |
+|---|---|---|
+| normal | 5 | 3 |
+| high (top-level skill names, protocol names) | 7 | 3 |
+| throwaway header | 3 | 2 |
+
+Word cap 80; at most 3 revision iterations.
 
 ## Anti-patterns
-- **Giving agents the body** - defeats the test (you're checking the label's *self-carrying* power).
-- **Running sequentially** - they'd anchor on each other; must be parallel.
-- **Tweaking one word on a FAIL** - step back and rethink the concept the label names, don't polish a wrong handle.
-- **Accepting "mostly right"** - a label that reliably misses a beat misleads every reader the same way. Fix it, or accept the rule is one-sided and split the body.
+
+- Showing the agents the body. That tests the body, not the label.
+- Running agents one after another; later ones anchor on earlier answers.
+- Changing one word after a FAIL. A FAIL means the concept behind the label is off; rethink it.
+- Accepting "mostly right". For a one-sided result, either fix the label or split the rule so each part has a label that fits.