From b21568b4e7867959cea107dc408084721de97d5a Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sun, 12 Jul 2026 10:21:55 +0200 Subject: [PATCH 1/8] [#313] docs: skill authoring effectiveness standard (T2) - writing-skills.mdx: add nine-principle effectiveness standard (description=trigger, information hierarchy + progressive disclosure, completion criteria, pruning, leading words, positive phrasing, co-location, constraints, evaluation), each with a how-to-check test, plus review checklist usable for T3-T6 - skills-guide.md (dataset + root mirror, prefix transform applied): condensed Authoring Standard section - ADR-010 records the standard: conformance-only guideline + corpus audit gaps as context; applies to new skills immediately, existing corpus refactored via #313 T3-T6; numbering assumes adr-009 (unmerged branch) lands first Refs: #313 T2, AC2 Co-Authored-By: Claude Fable 5 --- ...-skill-authoring-effectiveness-standard.md | 72 +++++++++++ .pair/knowledge/skills-guide.md | 14 +++ .../docs/contributing/writing-skills.mdx | 114 ++++++++++++++++-- .../dataset/.pair/knowledge/skills-guide.md | 14 +++ 4 files changed, 205 insertions(+), 9 deletions(-) create mode 100644 .pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md diff --git a/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md b/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md new file mode 100644 index 00000000..1236a88f --- /dev/null +++ b/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md @@ -0,0 +1,72 @@ +# ADR-010: Skill Authoring Effectiveness Standard + +**Status:** Accepted +**Date:** 2026-07-12 +**Context:** Story #313 (Skill corpus effectiveness) — Task T2 + +> Numbering note: `adr-009` exists on an unmerged branch at the time of writing; this ADR takes the next free number on the assumption that branch merges first. Renumber to 009 only if that branch is abandoned. + +## Decision + +Adopt a nine-principle **effectiveness standard** as the authoring bar for every Pair skill — new and existing — and as the review checklist for every skill edit: + +1. **Description = trigger** — description states what the skill is + its distinct trigger branches (one trigger per branch); mostly-composed capabilities carry a lean reach clause; body identity stays out of the description. +2. **Information hierarchy** — steps > in-file reference > disclosed reference (sibling file behind a context pointer whose wording determines reach); progressive disclosure licensed by branching. +3. **Completion criteria** — every Verify beat checkable (done vs not-done decidable) and exhaustive where thoroughness matters. +4. **Pruning discipline** — single source of truth per meaning; relevance test per line; no-op test per sentence (delete whole failing sentences); clear sediment on every edit. +5. **Leading words** — compact pretrained concepts repeated as tokens to anchor execution (body) and invocation (description). +6. **Positive phrasing** — target behavior stated; prohibitions only as hard guardrails paired with the positive target. +7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. +8. **Constraints** — `name` + `description` ≤ 1024 chars (agentskills.io); dataset skills carry only agentskills.io-spec frontmatter — no assistant-specific fields (portability across assistants); dataset + installed mirror updated in the same commit. +9. **Evaluation** — should-trigger / should-not-trigger prompt sets run in fresh sessions; description rewrites gated by before/after results. + +Documented in: + +- `apps/website/content/docs/contributing/writing-skills.mdx` — full standard, per-principle "how to check" tests, review checklist. +- `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md` (+ root mirror) — condensed "Authoring Standard" section. + +## Rationale + +The previous authoring guideline was **conformance-only**: it prescribed structure (frontmatter, C/S/A/V pattern, HALT, composition tables) but said nothing about what makes a skill trigger reliably or execute predictably. The corpus audit (2026-07-12, three sources: structural audit of all 35 skills; agentskills.io spec + Claude Code skill docs; the `writing-great-skills` reference model) found the corpus exemplary on conformance and weak on effectiveness: + +- 35/35 descriptions are capability summaries, not triggers; the 10 `assess-*` descriptions are near-clones. +- Recurring scaffold (cascade, idempotency, graceful degradation, record-decision contract) restated across 10–34 skills — ~35–65% of a typical skill. +- Zero progressive disclosure: 35 monolithic SKILL.md; orchestrators keep HALT rules ~380 lines from the phases they govern. +- A substantial minority of Verify beats are trivially satisfiable ("internally consistent", "guidelines loaded"). +- A meaning-preserving slimming pass yielded only −1.8%, confirming the gains are structural, not verbosity. + +A standard fixes the root cause: without an effectiveness bar, every future skill reproduces these gaps and the corpus needs periodic slimming passes instead of staying lean by discipline. + +**Alternatives considered:** + +1. **Keep conformance-only guideline, fix skills ad hoc** — rejected: no bar for new skills; regressions guaranteed; T3–T6 would have no shared review criteria. +2. **Adopt the reference model verbatim (link out to `writing-great-skills`)** — rejected: external repo not under our control; vocabulary must be reimplemented in Pair's own voice and bound to Pair's mechanics (dataset/mirror, composition, C/S/A/V). +3. **Enforce everything via tooling only** — rejected: only principle 8 (limits, frontmatter portability) and parts of 9 are statically checkable; the rest need a written standard applied in review. + +## Consequences + +**Positive:** + +- New skills must meet the standard immediately; the review checklist makes it enforceable in PR review. +- Existing corpus is refactored to the standard via #313 T3–T6 (descriptions, dedup, disclosure, criteria/steering), gated by the T7 eval. +- Shared conventions converge on single sources of truth — one-place edits instead of 10–34-file sweeps. +- Description rewrites become evidence-based (before/after trigger eval) instead of taste-based. + +**Negative:** + +- Authoring a skill costs more up front (trigger analysis, eval run, checklist pass). +- The eval (T7) adds a manual, fresh-session procedure until automated. +- Principles 1–7 remain judgement calls in review; only constraints and eval evidence are mechanically checkable. + +## Adoption Impact + +- `apps/website/content/docs/contributing/writing-skills.mdx` — extended with the effectiveness standard + review checklist. +- `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md` and root mirror `.pair/knowledge/skills-guide.md` — new "Authoring Standard" section. +- Applies to all future skill PRs; #313 T3–T6 apply it to the existing 35 skills. + +## References + +- Story: #313 (Skill corpus effectiveness), Task T2; AC2. +- Agent Skills specification: https://agentskills.io +- Reference model: `mattpocock/skills` — `writing-great-skills` skill + glossary (predictability as root virtue). +- Corpus audit evidence: #313 Background section (2026-07-12). diff --git a/.pair/knowledge/skills-guide.md b/.pair/knowledge/skills-guide.md index b5a070ed..d0e37f48 100644 --- a/.pair/knowledge/skills-guide.md +++ b/.pair/knowledge/skills-guide.md @@ -149,6 +149,20 @@ Process skills compose capability skills with optional graceful degradation: Optional skills degrade gracefully: if not installed, the process skill warns and continues without blocking. +## Authoring Standard + +Every skill is held to an effectiveness standard, not just structural conformance. The goal is predictability — the executor takes the same *process* every run. Nine principles, each with its check (full standard with worked examples and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): + +1. **Description = trigger** — the description states what the skill is plus its distinct trigger branches, one trigger per branch (synonyms restating a branch are duplication); mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/pair-process-refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* +2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference disclosed to a sibling file behind a context pointer whose wording (not its target) decides when it's loaded; inline what every run needs, disclose what only some branches reach. *Check: "does every run need this before acting?" decides the rung.* +3. **Completion criteria** — every Verify beat is checkable (done vs not-done decidable from observable state) and exhaustive where thoroughness matters; vague criteria invite premature completion. *Check: two executors couldn't disagree on whether it's satisfied.* +4. **Pruning** — single source of truth per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op test (does it change behavior vs the model default? delete whole failing sentences); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* +5. **Leading words** — compact pretrained concepts repeated as tokens (*idempotent*, *scope*, *gate*, *halt*) anchor behavior in the body and invocation in the description at minimal token cost. *Check: prose restating one idea across sentences collapses into one strong word.* +6. **Positive phrasing** — state the target behavior; a prohibition names the banned behavior into context; keep one only as a hard guardrail, paired with the positive target. *Check: each "never" survives an attempted positive rewrite.* +7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. *Check: no load-bearing rule stranded in a distant Notes section.* +8. **Constraints** — `name` + `description` ≤ 1024 characters (agentskills.io limit); dataset skills carry only agentskills.io-spec frontmatter (`name` + `description` required, spec-defined optionals like `version` allowed — no assistant-specific fields); dataset and installed mirror change in the same commit. *Check: char count, frontmatter field diff, commit touches both copies.* +9. **Evaluation** — should-trigger / should-not-trigger prompt sets per skill family, run in fresh sessions; description rewrites record before/after results, and a regression reverts the rewrite. *Check: evidence recorded per rewritten description.* + ## Callers Matrix (Scoped Capabilities) `/pair-capability-map-subdomains` and `/pair-capability-map-contexts` are capabilities, not process steps: every caller invokes them with `$scope` set to the items it just touched. `/pair-process-bootstrap` is the only caller allowed a full-catalog `$scope: all` run. diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 6dbd4267..d7622a07 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -1,11 +1,11 @@ --- title: Writing Skills -description: How to create Agent Skills for pair — directory structure, SKILL.md anatomy, composition, and testing. +description: How to create Agent Skills for pair — directory structure, SKILL.md anatomy, composition, the effectiveness standard, and testing. --- Agent Skills are structured instructions that AI coding assistants discover and execute. They follow the [Agent Skills](https://agentskills.io) open standard, supported by Claude Code, Cursor, VS Code Copilot, and OpenAI Codex. -This guide walks you through creating a new skill for the pair Knowledge Base. +This guide has two parts: the **mechanics** of a pair skill (structure, anatomy, composition), and the **effectiveness standard** — what makes a skill trigger reliably and execute predictably. A skill exists to make an agent take the same *process* every run, not produce the same output; every rule below is a lever on that predictability. ## Skill types @@ -95,7 +95,9 @@ What happens when dependencies are missing. | Field | Required | Description | |-------|----------|-------------| | `name` | Yes | Skill identifier, matches directory name | -| `description` | Yes | Brief description (used by AI tools for discovery) | +| `description` | Yes | Trigger-oriented description (used by AI tools for discovery — see [Description = trigger](#1-description--trigger)) | + +Frontmatter is bound by hard [constraints](#8-constraints): size limits and portability rules. ## Composition model @@ -130,6 +132,97 @@ This pattern ensures **idempotency** — re-running a skill skips already-comple Skills define explicit HALT conditions — situations where the skill stops and waits for developer input rather than proceeding with incomplete information. +## The effectiveness standard + +Conformance to the anatomy above makes a skill *valid*; it does not make it *effective*. This standard is the authoring bar for every new skill and the review checklist for every edit (recorded as ADR-010). Each principle ends with a **How to check** test you can run against the skill text alone. + +### 1. Description = trigger + +The frontmatter `description` does two jobs: state what the skill is, and list the **trigger branches** — the distinct situations in which an agent should load it. Rules: + +- **One trigger per branch.** Synonyms that rename the same branch are duplication — "evaluates the tech stack … use when choosing technologies" states one branch twice. Collapse them; keep only genuinely distinct branches. +- **Reach clause for composed capabilities.** A capability that fires mostly through composition by other skills carries a lean reach clause ("Composed by `/refine-story` and `/plan-tasks`; invoke directly when …") instead of a prompt-trigger list. +- **Body identity stays in the body.** Algorithm detail, step structure, and output format belong below the frontmatter. The description is loaded on every turn of every session, so it earns the hardest pruning in the file. + +**How to check:** map every description clause to a distinct trigger branch; two clauses on one branch collapse into one. Any clause that only matters *after* the skill is loaded moves to the body. + +### 2. Information hierarchy + +A skill's content sits on a ladder ranked by how immediately the executor needs it: + +1. **Steps** — ordered actions in `SKILL.md`, the primary tier. +2. **In-file reference** — definitions, rules, and tables consulted on demand. +3. **Disclosed reference** — a sibling `.md` file in the skill directory, reached through a **context pointer** whose *wording* — not its target — determines when and how reliably the executor loads it. + +**Progressive disclosure** — moving reference down the ladder into a sibling file — protects the legibility of the top: steps buried under reference turn attending to them into a coin flip. Disclosure is licensed by **branching**: inline what every run needs; push behind a pointer what only some paths reach. When a pointer fires unreliably on must-have material, sharpen its wording first; inline the material only if sharpening fails. + +**How to check:** for each block ask "does every run need this before acting?" — yes: keep it with the steps; on demand: in-file reference; only some branches: sibling file behind a sharply worded pointer. + +### 3. Completion criteria + +Every step's **Verify** beat must be *checkable* — an executor can decide done vs not-done from observable state — and *exhaustive* where thoroughness matters ("every AC has a mapped task", not "coverage looks reasonable"). A vague criterion ("internally consistent", "guidelines loaded") is trivially satisfiable and invites **premature completion**: the executor's attention slips to being done instead of doing. Where the real gate is human judgement, write an explicit human approval gate rather than a soft self-assessment. + +**How to check:** for each Verify beat, ask "could two executors disagree on whether this is satisfied?" If yes, rewrite it as an observable condition or an explicit approval gate. + +### 4. Pruning discipline + +Four tests keep a skill lean, run on every edit — pruning by discipline, not by periodic slimming passes: + +- **Single source of truth** — each meaning lives in exactly one authoritative place. A convention shared by many skills lives in one KB reference; each skill keeps only its delta. Two up-to-date copies are still a bug: the next edit desynchronizes them. +- **Relevance**, per line — does it still bear on what the skill does? +- **No-op**, per sentence — does it change behavior versus what the model does by default? When a sentence fails, delete the whole sentence; rewriting a no-op just produces a shorter no-op. +- **Sediment** — stale layers settle because adding feels safe and removing feels risky. Treat every edit as a chance to clear the layer you're touching. + +**How to check:** run relevance + no-op on every section you touch, and search the corpus for the meaning you're about to add — if it already lives somewhere, point to it instead of restating it. + +### 5. Leading words + +A **leading word** is a compact concept the model already holds from pretraining (*idempotent*, *scope*, *gate*, *halt*, *delta*), repeated as a token to anchor a whole region of behavior in the fewest tokens. In the body it anchors *execution* — the executor reaches for the same behavior each time the word appears. In the description it anchors *invocation* — when the same word lives in the user's prompts and the project's docs, the skill fires more reliably. + +**How to check:** a passage restating one quality across several sentences is a collapse candidate for one strong word. A leading word too weak to beat the model's default ("be thorough") fails the no-op test; the fix is a stronger word, not more prose. + +### 6. Positive phrasing + +State the target behavior. A prohibition names the banned behavior into context and makes it *more* available, not less — "never write verbose output" makes verbosity the freshest pattern the executor has read. A prohibition earns its place only as a hard guardrail you cannot phrase positively, and even then it is paired with the positive target so attention lands on what to do. + +**How to check:** for every "never"/"don't", attempt the positive rewrite ("write one-line summaries"). Keep the negation only where the rewrite loses the guardrail — and confirm the positive target sits beside it. + +### 7. Co-location + +Keep a concept's definition, rules, and caveats under one heading, adjacent to the step they govern, so reading one part brings its neighbors with it. A load-bearing rule buried in a Notes section hundreds of lines from the step it constrains is a variance bug: whether the executor attends to it becomes a coin flip. Co-location is distinct from duplication — duplication repeats one meaning in two places; scattering fragments one meaning across many. + +**How to check:** for each load-bearing concept, search the skill: if its rules appear under more than one heading (other than a context pointer), regroup them under the concept's own heading. + +### 8. Constraints + +Hard mechanics on top of the principles: + +- **Size limits** — `name` + `description` together stay within 1024 characters (the [agentskills.io](https://agentskills.io) limit). +- **Portability** — dataset skills carry only frontmatter the agentskills.io spec defines (`name` and `description` required; spec-defined optionals like `version` allowed). Assistant-specific fields (e.g., `disable-model-invocation`) stay out of the dataset: a skill must install identically on Claude Code, Cursor, VS Code Copilot, and Codex. +- **Mirror sync** — the dataset copy (`packages/knowledge-hub/dataset/.skills/`) and the installed mirror (`.claude/skills/`) change in the same commit, always. + +**How to check:** character-count the frontmatter; diff its fields against the core spec list; confirm the commit touches both copies. + +### 9. Evaluation + +A description rewrite is a hypothesis; the eval is the experiment. Maintain a **should-trigger / should-not-trigger** prompt set per skill family: prompts that must load the skill, and near-miss prompts that must not. Run it in fresh sessions — triggering is a cold-start behavior, so conversation history invalidates the result. When rewriting a description, run the set against both the old and the new description and record the before/after results; a regression reverts the rewrite, and you iterate on the description, not on the eval. + +**How to check:** before/after results are recorded for every rewritten description; each skill family has prompts on both sides of the trigger boundary. + +## Review checklist + +One line per principle — use it when authoring or reviewing any skill change: + +- [ ] Every description clause maps to a distinct trigger branch (or a lean reach clause for composed capabilities); no body identity in the description +- [ ] Steps lead; in-file reference only where most runs need it; branch-specific material disclosed behind a sharply worded pointer +- [ ] Every Verify beat checkable (done vs not-done decidable) and exhaustive where thoroughness matters +- [ ] No meaning duplicated (in-skill or cross-skill); every touched line passes relevance, every sentence the no-op test +- [ ] Recurring concepts anchored by leading words, not restated prose +- [ ] Prohibitions only as hard guardrails, each paired with its positive target +- [ ] Each concept's rules co-located under one heading, adjacent to the step they govern +- [ ] `name` + `description` ≤ 1024 chars; agentskills.io-spec frontmatter only (no assistant-specific fields); dataset + mirror in the same commit +- [ ] Description rewrites carry before/after trigger-eval evidence + ## Writing a new skill ### 1. Choose the skill type @@ -146,13 +239,14 @@ mkdir -p packages/knowledge-hub/dataset/.pair/knowledge/skills// ### 3. Write the SKILL.md -Follow the anatomy above. Key principles: +Follow the anatomy above and hold the draft to the [effectiveness standard](#the-effectiveness-standard). Key principles: - **Be explicit** — AI agents follow instructions literally. Ambiguity leads to incorrect behavior. - **Use the Check/Skip/Act/Verify pattern** — Ensures idempotency. - **Define HALT conditions** — Better to stop and ask than to proceed incorrectly. - **Document composition** — List all composed skills with required/optional status. - **Include graceful degradation** — What happens when optional dependencies are missing. +- **Pass the review checklist** — Every box above, before opening the PR. ### 4. Update the skills guide @@ -161,10 +255,11 @@ Add your skill to `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.m ### 5. Test the skill 1. Install the KB locally: run `pair install` or copy the SKILL.md to `.claude/skills//`. -2. Invoke the skill via the slash command (e.g., `/pair-capability-example`). -3. Verify the skill follows its algorithm correctly. -4. Test idempotency — re-invoke and confirm it skips completed steps. -5. Test graceful degradation — remove optional composed skills and verify the warning behavior. +2. Run the trigger eval: should-trigger and should-not-trigger prompts in fresh sessions (see [Evaluation](#9-evaluation)). +3. Invoke the skill via the slash command (e.g., `/pair-capability-example`). +4. Verify the skill follows its algorithm correctly. +5. Test idempotency — re-invoke and confirm it skips completed steps. +6. Test graceful degradation — remove optional composed skills and verify the warning behavior. ## Naming conventions @@ -176,6 +271,7 @@ Add your skill to `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.m ## Resources -- [Agent Skills specification](https://agentskills.io) — The open standard. +- [Agent Skills specification](https://agentskills.io) — The open standard, including frontmatter fields and size limits. +- [`writing-great-skills`](https://github.com/mattpocock/skills) — The reference model behind the effectiveness standard (predictability, information hierarchy, leading words, pruning). - [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 35 pair skills. - [Skills concept](/docs/concepts/skills) — How skills fit into the pair ecosystem. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md index 769869e5..eef057b9 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md @@ -149,6 +149,20 @@ Process skills compose capability skills with optional graceful degradation: Optional skills degrade gracefully: if not installed, the process skill warns and continues without blocking. +## Authoring Standard + +Every skill is held to an effectiveness standard, not just structural conformance. The goal is predictability — the executor takes the same *process* every run. Nine principles, each with its check (full standard with worked examples and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): + +1. **Description = trigger** — the description states what the skill is plus its distinct trigger branches, one trigger per branch (synonyms restating a branch are duplication); mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* +2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference disclosed to a sibling file behind a context pointer whose wording (not its target) decides when it's loaded; inline what every run needs, disclose what only some branches reach. *Check: "does every run need this before acting?" decides the rung.* +3. **Completion criteria** — every Verify beat is checkable (done vs not-done decidable from observable state) and exhaustive where thoroughness matters; vague criteria invite premature completion. *Check: two executors couldn't disagree on whether it's satisfied.* +4. **Pruning** — single source of truth per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op test (does it change behavior vs the model default? delete whole failing sentences); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* +5. **Leading words** — compact pretrained concepts repeated as tokens (*idempotent*, *scope*, *gate*, *halt*) anchor behavior in the body and invocation in the description at minimal token cost. *Check: prose restating one idea across sentences collapses into one strong word.* +6. **Positive phrasing** — state the target behavior; a prohibition names the banned behavior into context; keep one only as a hard guardrail, paired with the positive target. *Check: each "never" survives an attempted positive rewrite.* +7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. *Check: no load-bearing rule stranded in a distant Notes section.* +8. **Constraints** — `name` + `description` ≤ 1024 characters (agentskills.io limit); dataset skills carry only agentskills.io-spec frontmatter (`name` + `description` required, spec-defined optionals like `version` allowed — no assistant-specific fields); dataset and installed mirror change in the same commit. *Check: char count, frontmatter field diff, commit touches both copies.* +9. **Evaluation** — should-trigger / should-not-trigger prompt sets per skill family, run in fresh sessions; description rewrites record before/after results, and a regression reverts the rewrite. *Check: evidence recorded per rewritten description.* + ## Callers Matrix (Scoped Capabilities) `/map-subdomains` and `/map-contexts` are capabilities, not process steps: every caller invokes them with `$scope` set to the items it just touched. `/bootstrap` is the only caller allowed a full-catalog `$scope: all` run. From 530dfe60c6d352310b254bcf2298a2a2e767b0d9 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sun, 12 Jul 2026 10:45:38 +0200 Subject: [PATCH 2/8] =?UTF-8?q?[#313]=20fix:=20T2=20review=20remediation?= =?UTF-8?q?=20=E2=80=94=20spec=20accuracy,=20de-verbatim=20reference=20tex?= =?UTF-8?q?t,=20decidable=20checks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...-skill-authoring-effectiveness-standard.md | 2 +- .pair/knowledge/skills-guide.md | 4 ++-- .../docs/contributing/writing-skills.mdx | 22 +++++++++---------- .../dataset/.pair/knowledge/skills-guide.md | 4 ++-- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md b/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md index 1236a88f..2afc0d2b 100644 --- a/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md +++ b/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md @@ -17,7 +17,7 @@ Adopt a nine-principle **effectiveness standard** as the authoring bar for every 5. **Leading words** — compact pretrained concepts repeated as tokens to anchor execution (body) and invocation (description). 6. **Positive phrasing** — target behavior stated; prohibitions only as hard guardrails paired with the positive target. 7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. -8. **Constraints** — `name` + `description` ≤ 1024 chars (agentskills.io); dataset skills carry only agentskills.io-spec frontmatter — no assistant-specific fields (portability across assistants); dataset + installed mirror updated in the same commit. +8. **Constraints** — spec caps `name` ≤ 64 / `description` ≤ 1024 chars separately, Pair adds a stricter combined ≤1024 bound; dataset skills carry only agentskills.io-spec top-level frontmatter (`name`, `description`, and the optional `license`/`compatibility`/`metadata`/`allowed-tools`) plus `version`/`author` as a tolerated Pair extension for provenance — no assistant-specific fields (portability across assistants); dataset + installed mirror updated in the same commit. 9. **Evaluation** — should-trigger / should-not-trigger prompt sets run in fresh sessions; description rewrites gated by before/after results. Documented in: diff --git a/.pair/knowledge/skills-guide.md b/.pair/knowledge/skills-guide.md index d0e37f48..e0e3c8d8 100644 --- a/.pair/knowledge/skills-guide.md +++ b/.pair/knowledge/skills-guide.md @@ -151,7 +151,7 @@ Optional skills degrade gracefully: if not installed, the process skill warns an ## Authoring Standard -Every skill is held to an effectiveness standard, not just structural conformance. The goal is predictability — the executor takes the same *process* every run. Nine principles, each with its check (full standard with worked examples and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): +Every skill is held to an effectiveness standard, not just structural conformance. The goal is predictability — the executor takes the same *process* every run. Nine principles, each with its check (full standard, with illustrative examples, and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): 1. **Description = trigger** — the description states what the skill is plus its distinct trigger branches, one trigger per branch (synonyms restating a branch are duplication); mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/pair-process-refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* 2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference disclosed to a sibling file behind a context pointer whose wording (not its target) decides when it's loaded; inline what every run needs, disclose what only some branches reach. *Check: "does every run need this before acting?" decides the rung.* @@ -160,7 +160,7 @@ Every skill is held to an effectiveness standard, not just structural conformanc 5. **Leading words** — compact pretrained concepts repeated as tokens (*idempotent*, *scope*, *gate*, *halt*) anchor behavior in the body and invocation in the description at minimal token cost. *Check: prose restating one idea across sentences collapses into one strong word.* 6. **Positive phrasing** — state the target behavior; a prohibition names the banned behavior into context; keep one only as a hard guardrail, paired with the positive target. *Check: each "never" survives an attempted positive rewrite.* 7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. *Check: no load-bearing rule stranded in a distant Notes section.* -8. **Constraints** — `name` + `description` ≤ 1024 characters (agentskills.io limit); dataset skills carry only agentskills.io-spec frontmatter (`name` + `description` required, spec-defined optionals like `version` allowed — no assistant-specific fields); dataset and installed mirror change in the same commit. *Check: char count, frontmatter field diff, commit touches both copies.* +8. **Constraints** — the spec caps `name` at 64 and `description` at 1024 characters separately; Pair adopts a stricter combined ≤1024 bound for both together. Dataset skills carry only agentskills.io-spec top-level frontmatter (`name` + `description` required; optional `license`, `compatibility`, `metadata`, `allowed-tools`) plus `version`/`author` as a tolerated Pair extension at top level (the spec only shows those under `metadata:`) for provenance tracking — no assistant-specific fields. Dataset and installed mirror change in the same commit. *Check: char count against the combined bound, frontmatter field diff against spec + tolerated extension, commit touches both copies.* 9. **Evaluation** — should-trigger / should-not-trigger prompt sets per skill family, run in fresh sessions; description rewrites record before/after results, and a regression reverts the rewrite. *Check: evidence recorded per rewritten description.* ## Callers Matrix (Scoped Capabilities) diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index d7622a07..0f0ebd5c 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -140,7 +140,7 @@ Conformance to the anatomy above makes a skill *valid*; it does not make it *eff The frontmatter `description` does two jobs: state what the skill is, and list the **trigger branches** — the distinct situations in which an agent should load it. Rules: -- **One trigger per branch.** Synonyms that rename the same branch are duplication — "evaluates the tech stack … use when choosing technologies" states one branch twice. Collapse them; keep only genuinely distinct branches. +- **One trigger per branch.** Two clauses naming the same situation in different words still describe one branch — "evaluates the tech stack … use when choosing technologies" is a single trigger stated twice, not two. Merge such pairs down to the one branch they actually cover. - **Reach clause for composed capabilities.** A capability that fires mostly through composition by other skills carries a lean reach clause ("Composed by `/refine-story` and `/plan-tasks`; invoke directly when …") instead of a prompt-trigger list. - **Body identity stays in the body.** Algorithm detail, step structure, and output format belong below the frontmatter. The description is loaded on every turn of every session, so it earns the hardest pruning in the file. @@ -171,25 +171,25 @@ Four tests keep a skill lean, run on every edit — pruning by discipline, not b - **Single source of truth** — each meaning lives in exactly one authoritative place. A convention shared by many skills lives in one KB reference; each skill keeps only its delta. Two up-to-date copies are still a bug: the next edit desynchronizes them. - **Relevance**, per line — does it still bear on what the skill does? - **No-op**, per sentence — does it change behavior versus what the model does by default? When a sentence fails, delete the whole sentence; rewriting a no-op just produces a shorter no-op. -- **Sediment** — stale layers settle because adding feels safe and removing feels risky. Treat every edit as a chance to clear the layer you're touching. +- **Sediment** — a skill only ever grows by default, because appending a new rule feels low-risk while deleting an old one feels like it might break something for someone. Nobody schedules a pass to remove what's no longer true, so it doesn't happen on its own. Make removal part of the edit you're already making, not a separate pass you'll get to later. **How to check:** run relevance + no-op on every section you touch, and search the corpus for the meaning you're about to add — if it already lives somewhere, point to it instead of restating it. ### 5. Leading words -A **leading word** is a compact concept the model already holds from pretraining (*idempotent*, *scope*, *gate*, *halt*, *delta*), repeated as a token to anchor a whole region of behavior in the fewest tokens. In the body it anchors *execution* — the executor reaches for the same behavior each time the word appears. In the description it anchors *invocation* — when the same word lives in the user's prompts and the project's docs, the skill fires more reliably. +A **leading word** is a compact concept the model already holds from pretraining (*idempotent*, *scope*, *gate*, *halt*, *delta*). Naming a behavior with one of these words is cheaper than describing it, because the word arrives pre-loaded with the behavior's shape — the model doesn't need the surrounding sentence to know what *halt* implies. Placement changes what the word does: written into a step, it keeps the executor's action consistent every time that step runs; written into the description, it keeps invocation consistent — a word that also shows up in the user's own prompts and the project's docs pulls the skill in more reliably. -**How to check:** a passage restating one quality across several sentences is a collapse candidate for one strong word. A leading word too weak to beat the model's default ("be thorough") fails the no-op test; the fix is a stronger word, not more prose. +**How to check:** find every sentence in the file that restates the same single quality; that set must either collapse into one recurring leading word, or you must be able to name why no existing pretrained word already carries it. A leading word too weak to beat the model's default ("be thorough") fails the no-op test; the fix is a stronger word, not more prose. ### 6. Positive phrasing -State the target behavior. A prohibition names the banned behavior into context and makes it *more* available, not less — "never write verbose output" makes verbosity the freshest pattern the executor has read. A prohibition earns its place only as a hard guardrail you cannot phrase positively, and even then it is paired with the positive target so attention lands on what to do. +State the target behavior. Telling the executor what not to do puts the banned behavior on the page, and the page is what it reads from next — "never skip the verify step" leaves *skip the verify step* as the most recent phrase in view, competing with the instruction meant to prevent it. Reach for a prohibition only when there is no positive behavior that closes the same gap — a true hard guardrail — and even then, write the positive target next to it so the executor has somewhere else to look. -**How to check:** for every "never"/"don't", attempt the positive rewrite ("write one-line summaries"). Keep the negation only where the rewrite loses the guardrail — and confirm the positive target sits beside it. +**How to check:** for every "never"/"don't", attempt the positive rewrite (e.g. swap "never merge without a green quality gate" for "merge only once the quality gate reports green"). Keep the negation only where the rewrite loses the guardrail — and confirm the positive target sits beside it. ### 7. Co-location -Keep a concept's definition, rules, and caveats under one heading, adjacent to the step they govern, so reading one part brings its neighbors with it. A load-bearing rule buried in a Notes section hundreds of lines from the step it constrains is a variance bug: whether the executor attends to it becomes a coin flip. Co-location is distinct from duplication — duplication repeats one meaning in two places; scattering fragments one meaning across many. +Group a concept's definition, its rules, and its exceptions under the one heading that governs the step they apply to, rather than letting them settle wherever they were written. A load-bearing rule buried in a Notes section hundreds of lines from the step it constrains is a variance bug: whether the executor attends to it becomes a coin flip. Co-location is not the same failure as duplication — duplication says the same thing twice in two places; poor co-location says one thing once, but in pieces spread across the file, so no single read of it is complete. **How to check:** for each load-bearing concept, search the skill: if its rules appear under more than one heading (other than a context pointer), regroup them under the concept's own heading. @@ -197,11 +197,11 @@ Keep a concept's definition, rules, and caveats under one heading, adjacent to t Hard mechanics on top of the principles: -- **Size limits** — `name` + `description` together stay within 1024 characters (the [agentskills.io](https://agentskills.io) limit). -- **Portability** — dataset skills carry only frontmatter the agentskills.io spec defines (`name` and `description` required; spec-defined optionals like `version` allowed). Assistant-specific fields (e.g., `disable-model-invocation`) stay out of the dataset: a skill must install identically on Claude Code, Cursor, VS Code Copilot, and Codex. +- **Size limits** — the spec caps `name` at 64 chars and `description` at 1024 chars separately; Pair adopts a stricter combined ≤1024 bound for both together. +- **Portability** — the [agentskills.io](https://agentskills.io) spec's top-level frontmatter fields are `name` and `description` (required) plus `license`, `compatibility`, `metadata`, and `allowed-tools` (optional); the spec's own example `version`/`author` keys live *under* `metadata:`, not top-level. Pair skills carry `version`/`author` at top level instead — a tolerated **Pair extension** beyond the spec's optional fields, kept there for provenance tracking (who authored/last bumped a skill) until a future skill-corpus pass considers moving them under `metadata:`. Assistant-specific fields (e.g., `disable-model-invocation`) stay out of the dataset regardless: a skill must install identically on Claude Code, Cursor, VS Code Copilot, and Codex. - **Mirror sync** — the dataset copy (`packages/knowledge-hub/dataset/.skills/`) and the installed mirror (`.claude/skills/`) change in the same commit, always. -**How to check:** character-count the frontmatter; diff its fields against the core spec list; confirm the commit touches both copies. +**How to check:** character-count `name` and `description` against the combined bound; diff the frontmatter's fields against the spec's top-level list plus the tolerated `version`/`author` extension — anything else is a portability violation; confirm the commit touches both copies. ### 9. Evaluation @@ -220,7 +220,7 @@ One line per principle — use it when authoring or reviewing any skill change: - [ ] Recurring concepts anchored by leading words, not restated prose - [ ] Prohibitions only as hard guardrails, each paired with its positive target - [ ] Each concept's rules co-located under one heading, adjacent to the step they govern -- [ ] `name` + `description` ≤ 1024 chars; agentskills.io-spec frontmatter only (no assistant-specific fields); dataset + mirror in the same commit +- [ ] `name` ≤ 64 / `description` ≤ 1024 chars separately (spec), and both together ≤ 1024 (Pair's stricter bound); frontmatter limited to spec fields + the tolerated `version`/`author` extension (no assistant-specific fields); dataset + mirror in the same commit - [ ] Description rewrites carry before/after trigger-eval evidence ## Writing a new skill diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md index eef057b9..591db592 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md @@ -151,7 +151,7 @@ Optional skills degrade gracefully: if not installed, the process skill warns an ## Authoring Standard -Every skill is held to an effectiveness standard, not just structural conformance. The goal is predictability — the executor takes the same *process* every run. Nine principles, each with its check (full standard with worked examples and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): +Every skill is held to an effectiveness standard, not just structural conformance. The goal is predictability — the executor takes the same *process* every run. Nine principles, each with its check (full standard, with illustrative examples, and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): 1. **Description = trigger** — the description states what the skill is plus its distinct trigger branches, one trigger per branch (synonyms restating a branch are duplication); mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* 2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference disclosed to a sibling file behind a context pointer whose wording (not its target) decides when it's loaded; inline what every run needs, disclose what only some branches reach. *Check: "does every run need this before acting?" decides the rung.* @@ -160,7 +160,7 @@ Every skill is held to an effectiveness standard, not just structural conformanc 5. **Leading words** — compact pretrained concepts repeated as tokens (*idempotent*, *scope*, *gate*, *halt*) anchor behavior in the body and invocation in the description at minimal token cost. *Check: prose restating one idea across sentences collapses into one strong word.* 6. **Positive phrasing** — state the target behavior; a prohibition names the banned behavior into context; keep one only as a hard guardrail, paired with the positive target. *Check: each "never" survives an attempted positive rewrite.* 7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. *Check: no load-bearing rule stranded in a distant Notes section.* -8. **Constraints** — `name` + `description` ≤ 1024 characters (agentskills.io limit); dataset skills carry only agentskills.io-spec frontmatter (`name` + `description` required, spec-defined optionals like `version` allowed — no assistant-specific fields); dataset and installed mirror change in the same commit. *Check: char count, frontmatter field diff, commit touches both copies.* +8. **Constraints** — the spec caps `name` at 64 and `description` at 1024 characters separately; Pair adopts a stricter combined ≤1024 bound for both together. Dataset skills carry only agentskills.io-spec top-level frontmatter (`name` + `description` required; optional `license`, `compatibility`, `metadata`, `allowed-tools`) plus `version`/`author` as a tolerated Pair extension at top level (the spec only shows those under `metadata:`) for provenance tracking — no assistant-specific fields. Dataset and installed mirror change in the same commit. *Check: char count against the combined bound, frontmatter field diff against spec + tolerated extension, commit touches both copies.* 9. **Evaluation** — should-trigger / should-not-trigger prompt sets per skill family, run in fresh sessions; description rewrites record before/after results, and a regression reverts the rewrite. *Check: evidence recorded per rewritten description.* ## Callers Matrix (Scoped Capabilities) From add16ebdb8deb8edf286c60d3dd2c25bbc262c5d Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sun, 12 Jul 2026 11:03:40 +0200 Subject: [PATCH 3/8] [#313] fix: complete de-verbatim pass on authoring standard (round 2) Round-1 fix was too narrow: rewrote 5 spots, missed further verbatim/ near-verbatim lifts from mattpocock/skills across the same section (intro, principles 1-4), incl 2 exact phrase matches. Full re-scan of effectiveness standard vs both source files; rewrote every passage sharing more than incidental structure/wording, preserving meaning. Applied same fixes to both skills-guide.md copies where echoed. --- .pair/knowledge/skills-guide.md | 8 +++--- .../docs/contributing/writing-skills.mdx | 26 +++++++++---------- .../dataset/.pair/knowledge/skills-guide.md | 8 +++--- 3 files changed, 21 insertions(+), 21 deletions(-) diff --git a/.pair/knowledge/skills-guide.md b/.pair/knowledge/skills-guide.md index e0e3c8d8..6f9e5b30 100644 --- a/.pair/knowledge/skills-guide.md +++ b/.pair/knowledge/skills-guide.md @@ -151,12 +151,12 @@ Optional skills degrade gracefully: if not installed, the process skill warns an ## Authoring Standard -Every skill is held to an effectiveness standard, not just structural conformance. The goal is predictability — the executor takes the same *process* every run. Nine principles, each with its check (full standard, with illustrative examples, and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): +Every skill is held to an effectiveness standard, not just structural conformance. The goal is repeatable execution — the executor follows the same steps each time, whatever the run produces. Nine principles, each with its check (full standard, with illustrative examples, and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): 1. **Description = trigger** — the description states what the skill is plus its distinct trigger branches, one trigger per branch (synonyms restating a branch are duplication); mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/pair-process-refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* -2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference disclosed to a sibling file behind a context pointer whose wording (not its target) decides when it's loaded; inline what every run needs, disclose what only some branches reach. *Check: "does every run need this before acting?" decides the rung.* -3. **Completion criteria** — every Verify beat is checkable (done vs not-done decidable from observable state) and exhaustive where thoroughness matters; vague criteria invite premature completion. *Check: two executors couldn't disagree on whether it's satisfied.* -4. **Pruning** — single source of truth per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op test (does it change behavior vs the model default? delete whole failing sentences); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* +2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference pushed to a sibling file pulled in through a context pointer (its phrasing, not its target, is what makes it fire reliably); keep inline what every run passes through, move out what only a subset of runs reach. *Check: "does every run need this before acting?" decides the rung.* +3. **Completion criteria** — every Verify beat leaves no room for a judgment call (from observable state alone, the step either happened or it didn't) and is exhaustive where thoroughness matters; a criterion loose enough to pass by default invites premature completion. *Check: two executors couldn't disagree on whether it's satisfied.* +4. **Pruning** — single source of truth per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op test (strip it out — would the model act differently without it? delete whole failing sentences); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* 5. **Leading words** — compact pretrained concepts repeated as tokens (*idempotent*, *scope*, *gate*, *halt*) anchor behavior in the body and invocation in the description at minimal token cost. *Check: prose restating one idea across sentences collapses into one strong word.* 6. **Positive phrasing** — state the target behavior; a prohibition names the banned behavior into context; keep one only as a hard guardrail, paired with the positive target. *Check: each "never" survives an attempted positive rewrite.* 7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. *Check: no load-bearing rule stranded in a distant Notes section.* diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 0f0ebd5c..68c5a2f3 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -5,7 +5,7 @@ description: How to create Agent Skills for pair — directory structure, SKILL. Agent Skills are structured instructions that AI coding assistants discover and execute. They follow the [Agent Skills](https://agentskills.io) open standard, supported by Claude Code, Cursor, VS Code Copilot, and OpenAI Codex. -This guide has two parts: the **mechanics** of a pair skill (structure, anatomy, composition), and the **effectiveness standard** — what makes a skill trigger reliably and execute predictably. A skill exists to make an agent take the same *process* every run, not produce the same output; every rule below is a lever on that predictability. +This guide has two parts: the **mechanics** of a pair skill (structure, anatomy, composition), and the **effectiveness standard** — what makes a skill trigger reliably and execute predictably. The goal isn't identical output — it's an agent that runs through identical steps on every invocation; everything in the standard below is aimed at protecting that repeatability. ## Skill types @@ -138,29 +138,29 @@ Conformance to the anatomy above makes a skill *valid*; it does not make it *eff ### 1. Description = trigger -The frontmatter `description` does two jobs: state what the skill is, and list the **trigger branches** — the distinct situations in which an agent should load it. Rules: +The frontmatter `description` carries a dual burden — it identifies the skill's purpose, and it enumerates the **trigger branches**: the distinct situations that should cause an agent to load it. Rules: - **One trigger per branch.** Two clauses naming the same situation in different words still describe one branch — "evaluates the tech stack … use when choosing technologies" is a single trigger stated twice, not two. Merge such pairs down to the one branch they actually cover. - **Reach clause for composed capabilities.** A capability that fires mostly through composition by other skills carries a lean reach clause ("Composed by `/refine-story` and `/plan-tasks`; invoke directly when …") instead of a prompt-trigger list. -- **Body identity stays in the body.** Algorithm detail, step structure, and output format belong below the frontmatter. The description is loaded on every turn of every session, so it earns the hardest pruning in the file. +- **Body identity stays in the body.** Algorithm detail, step structure, and output format belong below the frontmatter. Since every session reloads the description on every turn, its token cost compounds — which is exactly why it deserves the most aggressive trimming of anything in the file. **How to check:** map every description clause to a distinct trigger branch; two clauses on one branch collapse into one. Any clause that only matters *after* the skill is loaded moves to the body. ### 2. Information hierarchy -A skill's content sits on a ladder ranked by how immediately the executor needs it: +A skill's content falls into tiers, ordered by how soon after invocation the material actually gets used: -1. **Steps** — ordered actions in `SKILL.md`, the primary tier. -2. **In-file reference** — definitions, rules, and tables consulted on demand. -3. **Disclosed reference** — a sibling `.md` file in the skill directory, reached through a **context pointer** whose *wording* — not its target — determines when and how reliably the executor loads it. +1. **Steps** — the sequence of actions written directly into `SKILL.md`; this is the top tier, read first and acted on immediately. +2. **In-file reference** — definitions, rules, and tables that stay in `SKILL.md` but are only looked up when a step actually calls for them. +3. **Disclosed reference** — a sibling `.md` file kept in the skill directory, brought in through a **context pointer**. How reliably that happens hinges on the phrasing of the pointer itself, not on what it points to. -**Progressive disclosure** — moving reference down the ladder into a sibling file — protects the legibility of the top: steps buried under reference turn attending to them into a coin flip. Disclosure is licensed by **branching**: inline what every run needs; push behind a pointer what only some paths reach. When a pointer fires unreliably on must-have material, sharpen its wording first; inline the material only if sharpening fails. +**Progressive disclosure** — pushing reference material down into a sibling file — keeps the top of that stack readable: when reference piles up around the steps, whether the executor actually reads and follows them each time stops being a sure thing. Deciding what to disclose comes down to **branching** — how many paths actually reach the material: if every run passes through it, keep it inline; if only a subset of runs ever gets there, that subset is the candidate for a pointer. If a pointer meant to surface must-have material doesn't fire reliably, the first fix is rewording it; folding the content back into the main file is a last resort, reserved for when rewording hasn't solved the problem. **How to check:** for each block ask "does every run need this before acting?" — yes: keep it with the steps; on demand: in-file reference; only some branches: sibling file behind a sharply worded pointer. ### 3. Completion criteria -Every step's **Verify** beat must be *checkable* — an executor can decide done vs not-done from observable state — and *exhaustive* where thoroughness matters ("every AC has a mapped task", not "coverage looks reasonable"). A vague criterion ("internally consistent", "guidelines loaded") is trivially satisfiable and invites **premature completion**: the executor's attention slips to being done instead of doing. Where the real gate is human judgement, write an explicit human approval gate rather than a soft self-assessment. +Every step's **Verify** beat needs two properties. First, it must be *checkable*: given the current state of things, either the step obviously happened or it obviously didn't, with no judgment call needed in between. Second, where thoroughness actually matters, it must be *exhaustive* — say "every AC has a mapped task" rather than something as loose as "coverage looks reasonable." A criterion like "internally consistent" or "guidelines loaded" passes almost automatically, which opens the door to **premature completion** — the step gets marked finished because finishing became the goal, not because the underlying work actually got done. Where a human, not the executor, is the real judge, say so explicitly with an approval gate instead of dressing up a soft self-assessment as a check. **How to check:** for each Verify beat, ask "could two executors disagree on whether this is satisfied?" If yes, rewrite it as an observable condition or an explicit approval gate. @@ -168,9 +168,9 @@ Every step's **Verify** beat must be *checkable* — an executor can decide done Four tests keep a skill lean, run on every edit — pruning by discipline, not by periodic slimming passes: -- **Single source of truth** — each meaning lives in exactly one authoritative place. A convention shared by many skills lives in one KB reference; each skill keeps only its delta. Two up-to-date copies are still a bug: the next edit desynchronizes them. -- **Relevance**, per line — does it still bear on what the skill does? -- **No-op**, per sentence — does it change behavior versus what the model does by default? When a sentence fails, delete the whole sentence; rewriting a no-op just produces a shorter no-op. +- **Single source of truth** — pick one authoritative home for each meaning and have everything else point back to it, so changing the behavior means editing exactly one spot. A convention shared by many skills lives in one KB reference; each skill keeps only its delta. Two up-to-date copies are still a bug: the next edit desynchronizes them. +- **Relevance**, per line — if you deleted this line, would the skill actually lose something it depends on? +- **No-op**, per sentence — pull the sentence out and ask whether the model's behavior would change at all; if it wouldn't, the sentence wasn't doing any work. When a sentence fails, delete the whole sentence; rewriting a no-op just produces a shorter no-op. - **Sediment** — a skill only ever grows by default, because appending a new rule feels low-risk while deleting an old one feels like it might break something for someone. Nobody schedules a pass to remove what's no longer true, so it doesn't happen on its own. Make removal part of the edit you're already making, not a separate pass you'll get to later. **How to check:** run relevance + no-op on every section you touch, and search the corpus for the meaning you're about to add — if it already lives somewhere, point to it instead of restating it. @@ -215,7 +215,7 @@ One line per principle — use it when authoring or reviewing any skill change: - [ ] Every description clause maps to a distinct trigger branch (or a lean reach clause for composed capabilities); no body identity in the description - [ ] Steps lead; in-file reference only where most runs need it; branch-specific material disclosed behind a sharply worded pointer -- [ ] Every Verify beat checkable (done vs not-done decidable) and exhaustive where thoroughness matters +- [ ] Every Verify beat leaves no room for a judgment call, and is exhaustive where thoroughness matters - [ ] No meaning duplicated (in-skill or cross-skill); every touched line passes relevance, every sentence the no-op test - [ ] Recurring concepts anchored by leading words, not restated prose - [ ] Prohibitions only as hard guardrails, each paired with its positive target diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md index 591db592..53788aef 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md @@ -151,12 +151,12 @@ Optional skills degrade gracefully: if not installed, the process skill warns an ## Authoring Standard -Every skill is held to an effectiveness standard, not just structural conformance. The goal is predictability — the executor takes the same *process* every run. Nine principles, each with its check (full standard, with illustrative examples, and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): +Every skill is held to an effectiveness standard, not just structural conformance. The goal is repeatable execution — the executor follows the same steps each time, whatever the run produces. Nine principles, each with its check (full standard, with illustrative examples, and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): 1. **Description = trigger** — the description states what the skill is plus its distinct trigger branches, one trigger per branch (synonyms restating a branch are duplication); mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* -2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference disclosed to a sibling file behind a context pointer whose wording (not its target) decides when it's loaded; inline what every run needs, disclose what only some branches reach. *Check: "does every run need this before acting?" decides the rung.* -3. **Completion criteria** — every Verify beat is checkable (done vs not-done decidable from observable state) and exhaustive where thoroughness matters; vague criteria invite premature completion. *Check: two executors couldn't disagree on whether it's satisfied.* -4. **Pruning** — single source of truth per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op test (does it change behavior vs the model default? delete whole failing sentences); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* +2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference pushed to a sibling file pulled in through a context pointer (its phrasing, not its target, is what makes it fire reliably); keep inline what every run passes through, move out what only a subset of runs reach. *Check: "does every run need this before acting?" decides the rung.* +3. **Completion criteria** — every Verify beat leaves no room for a judgment call (from observable state alone, the step either happened or it didn't) and is exhaustive where thoroughness matters; a criterion loose enough to pass by default invites premature completion. *Check: two executors couldn't disagree on whether it's satisfied.* +4. **Pruning** — single source of truth per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op test (strip it out — would the model act differently without it? delete whole failing sentences); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* 5. **Leading words** — compact pretrained concepts repeated as tokens (*idempotent*, *scope*, *gate*, *halt*) anchor behavior in the body and invocation in the description at minimal token cost. *Check: prose restating one idea across sentences collapses into one strong word.* 6. **Positive phrasing** — state the target behavior; a prohibition names the banned behavior into context; keep one only as a hard guardrail, paired with the positive target. *Check: each "never" survives an attempted positive rewrite.* 7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. *Check: no load-bearing rule stranded in a distant Notes section.* From 2935c6678007b6116d0b210ce713dd442a2c38aa Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sun, 12 Jul 2026 11:26:57 +0200 Subject: [PATCH 4/8] [#313] fix: mechanical n-gram de-verbatim sweep (round 4) + ADR bare-URL fix --- ...-skill-authoring-effectiveness-standard.md | 2 +- .pair/knowledge/skills-guide.md | 8 +++---- .../docs/contributing/writing-skills.mdx | 22 +++++++++---------- .../dataset/.pair/knowledge/skills-guide.md | 8 +++---- 4 files changed, 20 insertions(+), 20 deletions(-) diff --git a/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md b/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md index 2afc0d2b..6dec512e 100644 --- a/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md +++ b/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md @@ -67,6 +67,6 @@ A standard fixes the root cause: without an effectiveness bar, every future skil ## References - Story: #313 (Skill corpus effectiveness), Task T2; AC2. -- Agent Skills specification: https://agentskills.io +- Agent Skills specification: - Reference model: `mattpocock/skills` — `writing-great-skills` skill + glossary (predictability as root virtue). - Corpus audit evidence: #313 Background section (2026-07-12). diff --git a/.pair/knowledge/skills-guide.md b/.pair/knowledge/skills-guide.md index 6f9e5b30..a65a58fe 100644 --- a/.pair/knowledge/skills-guide.md +++ b/.pair/knowledge/skills-guide.md @@ -153,13 +153,13 @@ Optional skills degrade gracefully: if not installed, the process skill warns an Every skill is held to an effectiveness standard, not just structural conformance. The goal is repeatable execution — the executor follows the same steps each time, whatever the run produces. Nine principles, each with its check (full standard, with illustrative examples, and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): -1. **Description = trigger** — the description states what the skill is plus its distinct trigger branches, one trigger per branch (synonyms restating a branch are duplication); mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/pair-process-refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* +1. **Description = trigger** — the description names the skill's purpose and enumerates its distinct trigger branches; two clauses covering the same branch in different words still collapse into one branch, so merge them; mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/pair-process-refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* 2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference pushed to a sibling file pulled in through a context pointer (its phrasing, not its target, is what makes it fire reliably); keep inline what every run passes through, move out what only a subset of runs reach. *Check: "does every run need this before acting?" decides the rung.* 3. **Completion criteria** — every Verify beat leaves no room for a judgment call (from observable state alone, the step either happened or it didn't) and is exhaustive where thoroughness matters; a criterion loose enough to pass by default invites premature completion. *Check: two executors couldn't disagree on whether it's satisfied.* -4. **Pruning** — single source of truth per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op test (strip it out — would the model act differently without it? delete whole failing sentences); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* +4. **Pruning** — one home per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op check (strip it out — would the model act differently without it? cut failing sentences outright); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* 5. **Leading words** — compact pretrained concepts repeated as tokens (*idempotent*, *scope*, *gate*, *halt*) anchor behavior in the body and invocation in the description at minimal token cost. *Check: prose restating one idea across sentences collapses into one strong word.* -6. **Positive phrasing** — state the target behavior; a prohibition names the banned behavior into context; keep one only as a hard guardrail, paired with the positive target. *Check: each "never" survives an attempted positive rewrite.* -7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. *Check: no load-bearing rule stranded in a distant Notes section.* +6. **Positive phrasing** — state what the executor should do; spelling out the banned behavior instead just pulls it into view. A prohibition belongs only where no positive phrasing closes the same gap, and even then the positive instruction sits right beside it. *Check: rewrite each "never" as a positive instruction; keep the negation only where that rewrite fails, with the positive alternative stated next to it.* +7. **Co-location** — a concept's definition, its rules, and its exceptions grouped under the one heading that governs the step, not scattered wherever they were written. *Check: no load-bearing rule stranded in a distant Notes section.* 8. **Constraints** — the spec caps `name` at 64 and `description` at 1024 characters separately; Pair adopts a stricter combined ≤1024 bound for both together. Dataset skills carry only agentskills.io-spec top-level frontmatter (`name` + `description` required; optional `license`, `compatibility`, `metadata`, `allowed-tools`) plus `version`/`author` as a tolerated Pair extension at top level (the spec only shows those under `metadata:`) for provenance tracking — no assistant-specific fields. Dataset and installed mirror change in the same commit. *Check: char count against the combined bound, frontmatter field diff against spec + tolerated extension, commit touches both copies.* 9. **Evaluation** — should-trigger / should-not-trigger prompt sets per skill family, run in fresh sessions; description rewrites record before/after results, and a regression reverts the rewrite. *Check: evidence recorded per rewritten description.* diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 68c5a2f3..6c1a258b 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -140,7 +140,7 @@ Conformance to the anatomy above makes a skill *valid*; it does not make it *eff The frontmatter `description` carries a dual burden — it identifies the skill's purpose, and it enumerates the **trigger branches**: the distinct situations that should cause an agent to load it. Rules: -- **One trigger per branch.** Two clauses naming the same situation in different words still describe one branch — "evaluates the tech stack … use when choosing technologies" is a single trigger stated twice, not two. Merge such pairs down to the one branch they actually cover. +- **A branch earns exactly one trigger.** Two clauses naming the same situation in different words still describe one branch — "evaluates the tech stack … use when choosing technologies" is a single trigger stated twice, not two. Merge such pairs down to the one branch they actually cover. - **Reach clause for composed capabilities.** A capability that fires mostly through composition by other skills carries a lean reach clause ("Composed by `/refine-story` and `/plan-tasks`; invoke directly when …") instead of a prompt-trigger list. - **Body identity stays in the body.** Algorithm detail, step structure, and output format belong below the frontmatter. Since every session reloads the description on every turn, its token cost compounds — which is exactly why it deserves the most aggressive trimming of anything in the file. @@ -148,13 +148,13 @@ The frontmatter `description` carries a dual burden — it identifies the skill' ### 2. Information hierarchy -A skill's content falls into tiers, ordered by how soon after invocation the material actually gets used: +Content in a skill sits at different depths, ranked by how soon after invocation it actually gets used: 1. **Steps** — the sequence of actions written directly into `SKILL.md`; this is the top tier, read first and acted on immediately. 2. **In-file reference** — definitions, rules, and tables that stay in `SKILL.md` but are only looked up when a step actually calls for them. -3. **Disclosed reference** — a sibling `.md` file kept in the skill directory, brought in through a **context pointer**. How reliably that happens hinges on the phrasing of the pointer itself, not on what it points to. +3. **Disclosed reference** — a same-directory `.md` file, folded in through a **context pointer**. How it's phrased is what decides whether it actually gets pulled in — the destination it names has no bearing on that. -**Progressive disclosure** — pushing reference material down into a sibling file — keeps the top of that stack readable: when reference piles up around the steps, whether the executor actually reads and follows them each time stops being a sure thing. Deciding what to disclose comes down to **branching** — how many paths actually reach the material: if every run passes through it, keep it inline; if only a subset of runs ever gets there, that subset is the candidate for a pointer. If a pointer meant to surface must-have material doesn't fire reliably, the first fix is rewording it; folding the content back into the main file is a last resort, reserved for when rewording hasn't solved the problem. +**Progressive disclosure** — pushing reference material down into a sibling file — keeps the top of that stack readable: when reference piles up around the steps, whether the executor actually reads and follows them each time stops being a sure thing. Deciding what to disclose comes down to **branching** — how many paths actually reach the material. Material every run touches belongs inline; once only a fraction of runs ever reach it, that fraction marks the cut point for a pointer. Rewrite the pointer's wording first when it fails to surface must-have material — that's the cheap, local fix; only fold the content back into the main file if repeated rewording still doesn't make it stick. **How to check:** for each block ask "does every run need this before acting?" — yes: keep it with the steps; on demand: in-file reference; only some branches: sibling file behind a sharply worded pointer. @@ -168,28 +168,28 @@ Every step's **Verify** beat needs two properties. First, it must be *checkable* Four tests keep a skill lean, run on every edit — pruning by discipline, not by periodic slimming passes: -- **Single source of truth** — pick one authoritative home for each meaning and have everything else point back to it, so changing the behavior means editing exactly one spot. A convention shared by many skills lives in one KB reference; each skill keeps only its delta. Two up-to-date copies are still a bug: the next edit desynchronizes them. +- **One home per meaning** — pick a single authoritative spot for each meaning and have everything else point back to it, so changing the behavior means editing exactly one place. A convention shared across many skills belongs in one KB reference, with each skill holding only its own delta. Two up-to-date copies are still a bug: the next edit desynchronizes them. - **Relevance**, per line — if you deleted this line, would the skill actually lose something it depends on? -- **No-op**, per sentence — pull the sentence out and ask whether the model's behavior would change at all; if it wouldn't, the sentence wasn't doing any work. When a sentence fails, delete the whole sentence; rewriting a no-op just produces a shorter no-op. +- **No-op**, per sentence — pull the sentence out and ask whether the model's behavior would change at all; if it wouldn't, the sentence wasn't doing any work. When a sentence fails that test, remove it in full — reworking a no-op only leaves behind a shorter no-op. - **Sediment** — a skill only ever grows by default, because appending a new rule feels low-risk while deleting an old one feels like it might break something for someone. Nobody schedules a pass to remove what's no longer true, so it doesn't happen on its own. Make removal part of the edit you're already making, not a separate pass you'll get to later. **How to check:** run relevance + no-op on every section you touch, and search the corpus for the meaning you're about to add — if it already lives somewhere, point to it instead of restating it. ### 5. Leading words -A **leading word** is a compact concept the model already holds from pretraining (*idempotent*, *scope*, *gate*, *halt*, *delta*). Naming a behavior with one of these words is cheaper than describing it, because the word arrives pre-loaded with the behavior's shape — the model doesn't need the surrounding sentence to know what *halt* implies. Placement changes what the word does: written into a step, it keeps the executor's action consistent every time that step runs; written into the description, it keeps invocation consistent — a word that also shows up in the user's own prompts and the project's docs pulls the skill in more reliably. +Certain words already carry a fully-formed behavior from what the model saw during pretraining — *idempotent*, *scope*, *gate*, *halt*, *delta* — call these **leading words**: naming one does the work a full explanation would otherwise need, because the model brings its own sense of what *halt* means without the sentence spelling it out. Where you place one changes what it stabilizes: inside a step it keeps the executor's action the same on every run; inside the description it keeps invocation itself consistent, especially when that same word also turns up in the user's prompts and the project's docs. -**How to check:** find every sentence in the file that restates the same single quality; that set must either collapse into one recurring leading word, or you must be able to name why no existing pretrained word already carries it. A leading word too weak to beat the model's default ("be thorough") fails the no-op test; the fix is a stronger word, not more prose. +**How to check:** scan the file for every sentence circling the same single quality; either they collapse into one recurring leading word, or there's a reason no pretrained word already covers it. Take an example like "be thorough" — it doesn't out-pull what the model does by default, so it earns nothing and should be swapped for a sharper word rather than padded with extra prose. ### 6. Positive phrasing -State the target behavior. Telling the executor what not to do puts the banned behavior on the page, and the page is what it reads from next — "never skip the verify step" leaves *skip the verify step* as the most recent phrase in view, competing with the instruction meant to prevent it. Reach for a prohibition only when there is no positive behavior that closes the same gap — a true hard guardrail — and even then, write the positive target next to it so the executor has somewhere else to look. +State the target behavior. Naming the behavior you don't want puts exactly that behavior on the page, and the page is what the executor reads from next — "never skip the verify step" leaves *skip the verify step* as the most recent phrase in view, competing with the instruction meant to prevent it. Reach for a prohibition only when there is no positive behavior that closes the same gap — a true hard guardrail — and even then, write the positive target next to it so the executor has somewhere else to look. **How to check:** for every "never"/"don't", attempt the positive rewrite (e.g. swap "never merge without a green quality gate" for "merge only once the quality gate reports green"). Keep the negation only where the rewrite loses the guardrail — and confirm the positive target sits beside it. ### 7. Co-location -Group a concept's definition, its rules, and its exceptions under the one heading that governs the step they apply to, rather than letting them settle wherever they were written. A load-bearing rule buried in a Notes section hundreds of lines from the step it constrains is a variance bug: whether the executor attends to it becomes a coin flip. Co-location is not the same failure as duplication — duplication says the same thing twice in two places; poor co-location says one thing once, but in pieces spread across the file, so no single read of it is complete. +Group a concept's definition, its rules, and its exceptions under the one heading that governs the step they apply to, rather than letting them settle wherever they were written. A load-bearing rule buried in a Notes section hundreds of lines from the step it constrains makes whether the executor notices it a toss-up between runs, not a certainty. Co-location is not the same failure as duplication — duplication says the same thing twice in two places; poor co-location says one thing once, but scattered as fragments throughout the document — no single pass through it gives the whole picture. **How to check:** for each load-bearing concept, search the skill: if its rules appear under more than one heading (other than a context pointer), regroup them under the concept's own heading. @@ -216,7 +216,7 @@ One line per principle — use it when authoring or reviewing any skill change: - [ ] Every description clause maps to a distinct trigger branch (or a lean reach clause for composed capabilities); no body identity in the description - [ ] Steps lead; in-file reference only where most runs need it; branch-specific material disclosed behind a sharply worded pointer - [ ] Every Verify beat leaves no room for a judgment call, and is exhaustive where thoroughness matters -- [ ] No meaning duplicated (in-skill or cross-skill); every touched line passes relevance, every sentence the no-op test +- [ ] No meaning duplicated (in-skill or cross-skill); every touched line passes relevance, every sentence clears the no-op check - [ ] Recurring concepts anchored by leading words, not restated prose - [ ] Prohibitions only as hard guardrails, each paired with its positive target - [ ] Each concept's rules co-located under one heading, adjacent to the step they govern diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md index 53788aef..991568fb 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md @@ -153,13 +153,13 @@ Optional skills degrade gracefully: if not installed, the process skill warns an Every skill is held to an effectiveness standard, not just structural conformance. The goal is repeatable execution — the executor follows the same steps each time, whatever the run produces. Nine principles, each with its check (full standard, with illustrative examples, and review checklist: website contributing guide "Writing Skills"; recorded as ADR-010): -1. **Description = trigger** — the description states what the skill is plus its distinct trigger branches, one trigger per branch (synonyms restating a branch are duplication); mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* +1. **Description = trigger** — the description names the skill's purpose and enumerates its distinct trigger branches; two clauses covering the same branch in different words still collapse into one branch, so merge them; mostly-composed capabilities carry a lean reach clause (e.g. "Composed by `/refine-story`; invoke directly when …") instead of a trigger list; algorithm detail stays in the body. *Check: every clause maps to a distinct branch; nothing that only matters after loading.* 2. **Information hierarchy** — steps first, in-file reference second, branch-specific reference pushed to a sibling file pulled in through a context pointer (its phrasing, not its target, is what makes it fire reliably); keep inline what every run passes through, move out what only a subset of runs reach. *Check: "does every run need this before acting?" decides the rung.* 3. **Completion criteria** — every Verify beat leaves no room for a judgment call (from observable state alone, the step either happened or it didn't) and is exhaustive where thoroughness matters; a criterion loose enough to pass by default invites premature completion. *Check: two executors couldn't disagree on whether it's satisfied.* -4. **Pruning** — single source of truth per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op test (strip it out — would the model act differently without it? delete whole failing sentences); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* +4. **Pruning** — one home per meaning (shared conventions live once; skills keep deltas); every line passes a relevance test; every sentence passes a no-op check (strip it out — would the model act differently without it? cut failing sentences outright); prune on every edit before sediment settles. *Check: the meaning you're adding doesn't already live elsewhere.* 5. **Leading words** — compact pretrained concepts repeated as tokens (*idempotent*, *scope*, *gate*, *halt*) anchor behavior in the body and invocation in the description at minimal token cost. *Check: prose restating one idea across sentences collapses into one strong word.* -6. **Positive phrasing** — state the target behavior; a prohibition names the banned behavior into context; keep one only as a hard guardrail, paired with the positive target. *Check: each "never" survives an attempted positive rewrite.* -7. **Co-location** — a concept's definition, rules, and caveats under one heading, adjacent to the step they govern. *Check: no load-bearing rule stranded in a distant Notes section.* +6. **Positive phrasing** — state what the executor should do; spelling out the banned behavior instead just pulls it into view. A prohibition belongs only where no positive phrasing closes the same gap, and even then the positive instruction sits right beside it. *Check: rewrite each "never" as a positive instruction; keep the negation only where that rewrite fails, with the positive alternative stated next to it.* +7. **Co-location** — a concept's definition, its rules, and its exceptions grouped under the one heading that governs the step, not scattered wherever they were written. *Check: no load-bearing rule stranded in a distant Notes section.* 8. **Constraints** — the spec caps `name` at 64 and `description` at 1024 characters separately; Pair adopts a stricter combined ≤1024 bound for both together. Dataset skills carry only agentskills.io-spec top-level frontmatter (`name` + `description` required; optional `license`, `compatibility`, `metadata`, `allowed-tools`) plus `version`/`author` as a tolerated Pair extension at top level (the spec only shows those under `metadata:`) for provenance tracking — no assistant-specific fields. Dataset and installed mirror change in the same commit. *Check: char count against the combined bound, frontmatter field diff against spec + tolerated extension, commit touches both copies.* 9. **Evaluation** — should-trigger / should-not-trigger prompt sets per skill family, run in fresh sessions; description rewrites record before/after results, and a regression reverts the rewrite. *Check: evidence recorded per rewritten description.* From 4e91b1cbac8896d05bcc8e3508603f272e2c823f Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sun, 12 Jul 2026 19:02:07 +0200 Subject: [PATCH 5/8] fix: remove project-specific story citation from checkpoint SKILL.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both the frontmatter description and the Composition Interface section cited "(story #256)" — a Pair-repo-specific issue number, meaningless to any project that installs this KB-shipped skill. KB guidelines and skills must not reference this repo's own ADRs, decision-log entries, or issue-tracker numbers, since they distribute in isolation to other projects. Removed both citations, dataset + installed mirror. Co-Authored-By: Claude Sonnet 5 --- .claude/skills/pair-capability-checkpoint/SKILL.md | 4 ++-- .../dataset/.skills/capability/checkpoint/SKILL.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/skills/pair-capability-checkpoint/SKILL.md b/.claude/skills/pair-capability-checkpoint/SKILL.md index 4b0384e1..e9bae850 100644 --- a/.claude/skills/pair-capability-checkpoint/SKILL.md +++ b/.claude/skills/pair-capability-checkpoint/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-checkpoint -description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives context resets. Write mode persists state to .pair/working/checkpoints/.md, one file per story; resume mode locates and parses it. Invocable independently; composed by a future closing phase of /pair-process-implement (story #256) and a future /pair-capability-publish-pr as a handoff." +description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives context resets. Write mode persists state to .pair/working/checkpoints/.md, one file per story; resume mode locates and parses it. Invocable independently; composed by a future closing phase of /pair-process-implement and a future /pair-capability-publish-pr as a handoff." version: 0.4.1 author: Foomakers --- @@ -114,7 +114,7 @@ CHECKPOINT RESUMED: ## Composition Interface -When composed by a future closing phase of `/pair-process-implement` (story #256): +When composed by a future closing phase of `/pair-process-implement`: - **Input**: `/pair-process-implement` would invoke `/pair-capability-checkpoint` with `$mode=write` between tasks (or on developer request) to persist progress, `$mode=resume` at Phase 0 when re-invoked on a story that may have been interrupted, and remove the checkpoint on story completion (cleanup). - **Output**: Write mode's returned text becomes the session's record of state. Resume mode's parsed state lets `/pair-process-implement` skip re-analysis and jump straight to the first pending task. diff --git a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md index e7d0550b..1a8ca3a2 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md @@ -1,6 +1,6 @@ --- name: checkpoint -description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives context resets. Write mode persists state to .pair/working/checkpoints/.md, one file per story; resume mode locates and parses it. Invocable independently; composed by a future closing phase of /implement (story #256) and a future /publish-pr as a handoff." +description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives context resets. Write mode persists state to .pair/working/checkpoints/.md, one file per story; resume mode locates and parses it. Invocable independently; composed by a future closing phase of /implement and a future /publish-pr as a handoff." version: 0.4.1 author: Foomakers --- @@ -114,7 +114,7 @@ CHECKPOINT RESUMED: ## Composition Interface -When composed by a future closing phase of `/implement` (story #256): +When composed by a future closing phase of `/implement`: - **Input**: `/implement` would invoke `/checkpoint` with `$mode=write` between tasks (or on developer request) to persist progress, `$mode=resume` at Phase 0 when re-invoked on a story that may have been interrupted, and remove the checkpoint on story completion (cleanup). - **Output**: Write mode's returned text becomes the session's record of state. Resume mode's parsed state lets `/implement` skip re-analysis and jump straight to the first pending task. From 175b0432e12c770ae67c53be46c908329fdec283 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sun, 12 Jul 2026 20:13:24 +0200 Subject: [PATCH 6/8] [#313] chore: T2b slim 14 mutex-excluded skills (meaning-preserving) Co-Authored-By: Claude Fable 5 --- .claude/skills/pair-capability-assess-ai/SKILL.md | 4 ++-- .../skills/pair-capability-assess-architecture/SKILL.md | 8 ++++---- .../skills/pair-capability-assess-code-quality/SKILL.md | 4 +--- .claude/skills/pair-capability-assess-debt/SKILL.md | 6 +----- .../pair-capability-assess-infrastructure/SKILL.md | 4 ++-- .../skills/pair-capability-assess-methodology/SKILL.md | 4 ++-- .../skills/pair-capability-assess-observability/SKILL.md | 4 ++-- .claude/skills/pair-capability-assess-pm/SKILL.md | 4 ++-- .claude/skills/pair-capability-assess-stack/SKILL.md | 6 ++---- .claude/skills/pair-capability-assess-testing/SKILL.md | 8 ++++---- .claude/skills/pair-capability-record-decision/SKILL.md | 9 +++------ .claude/skills/pair-capability-write-issue/SKILL.md | 3 +-- .claude/skills/pair-process-bootstrap/SKILL.md | 8 ++------ .claude/skills/pair-process-review/SKILL.md | 8 +++----- .../dataset/.skills/capability/assess-ai/SKILL.md | 4 ++-- .../.skills/capability/assess-architecture/SKILL.md | 8 ++++---- .../.skills/capability/assess-code-quality/SKILL.md | 4 +--- .../dataset/.skills/capability/assess-debt/SKILL.md | 6 +----- .../.skills/capability/assess-infrastructure/SKILL.md | 4 ++-- .../.skills/capability/assess-methodology/SKILL.md | 4 ++-- .../.skills/capability/assess-observability/SKILL.md | 4 ++-- .../dataset/.skills/capability/assess-pm/SKILL.md | 4 ++-- .../dataset/.skills/capability/assess-stack/SKILL.md | 6 ++---- .../dataset/.skills/capability/assess-testing/SKILL.md | 8 ++++---- .../dataset/.skills/capability/record-decision/SKILL.md | 9 +++------ .../dataset/.skills/capability/write-issue/SKILL.md | 3 +-- .../dataset/.skills/process/bootstrap/SKILL.md | 8 ++------ .../dataset/.skills/process/review/SKILL.md | 8 +++----- 28 files changed, 62 insertions(+), 98 deletions(-) diff --git a/.claude/skills/pair-capability-assess-ai/SKILL.md b/.claude/skills/pair-capability-assess-ai/SKILL.md index 276a007d..e3f28ce0 100644 --- a/.claude/skills/pair-capability-assess-ai/SKILL.md +++ b/.claude/skills/pair-capability-assess-ai/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend AI development tools: AI assistants, MCP integrations, AI ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -97,7 +97,7 @@ The rendered adoption content is destined for this section — the caller writes - MCP integrations if applicable - AI-specific SDKs and libraries with versions - Scope strictly to the AI section so the caller's write preserves all other sections (core, testing) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal diff --git a/.claude/skills/pair-capability-assess-architecture/SKILL.md b/.claude/skills/pair-capability-assess-architecture/SKILL.md index aedbaab1..2e0daf33 100644 --- a/.claude/skills/pair-capability-assess-architecture/SKILL.md +++ b/.claude/skills/pair-capability-assess-architecture/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend the system architecture pattern. Follows the resolution c ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -98,7 +98,7 @@ The rendered adoption content is destined for this file — the caller writes it - Concise, prescriptive statements (what IS adopted, not options) - Reference guidelines for detailed rationale - Scope the content to this skill's owned section so the caller's write preserves other sections -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal @@ -107,7 +107,7 @@ The rendered adoption content is destined for this file — the caller writes it - `target`: [adoption/tech/architecture.md](../../../.pair/adoption/tech/architecture.md) (owned section) - `decision-metadata`: `$type: architectural`, `$topic: architecture-pattern`, `$summary: "[Pattern] adopted as system architecture"` - plus the human-facing report (see Output Format) -2. **Verify**: Proposal emitted. Persistence — writing `content` to `target` and recording the ADR — is performed by the caller via `/pair-capability-record-decision(content, target, decision-metadata)`, never by this skill. +2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/pair-capability-record-decision(content, target, decision-metadata)`, never by this skill. ## Output Format @@ -132,7 +132,7 @@ When composed by `/pair-process-bootstrap`: When invoked **independently**: -- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits the changes. +- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits. ## Edge Cases diff --git a/.claude/skills/pair-capability-assess-code-quality/SKILL.md b/.claude/skills/pair-capability-assess-code-quality/SKILL.md index cc303c29..eef1080d 100644 --- a/.claude/skills/pair-capability-assess-code-quality/SKILL.md +++ b/.claude/skills/pair-capability-assess-code-quality/SKILL.md @@ -45,7 +45,7 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p - Size metrics: lines of code, function length, class/module size, file size - Quality metrics: test coverage, code duplication, maintainability index - Thresholds per metric (e.g., cyclomatic complexity 1-5 = simple, 16+ = refactor needed) -2. **Verify**: Guidelines loaded. If not found, use built-in thresholds. +2. **Verify**: Guidelines loaded. ### Step 3: Collect Metrics @@ -149,7 +149,6 @@ When composed by `/pair-process-review`: When invoked **independently**: - Full interactive flow. Developer receives the report and decides on improvement actions. -- This skill is **read-only** — it inspects code and runs tests (coverage) but does not modify files. ## Graceful Degradation @@ -162,7 +161,6 @@ When invoked **independently**: - This skill is **read-only / output-only** — it inspects code, runs coverage (via existing test commands), but never modifies files, adoption, or the PM tool. A finding worth tracking is promoted deliberately to the backlog via `/pair-capability-write-issue` (a manual, selective act) — never auto-created. - **Idempotent**: re-invocation checks staleness of existing report. If codebase unchanged → confirms existing report. If changed → re-assesses only. -- **Resolution cascade**: Path A (existing recent report) → Path B (full assessment). Follows the same cascade pattern as other assess-* skills. - Metrics are **health indicators, not absolute quality measures**. Context matters: business logic naturally has higher complexity, and metric targets should align with team capabilities. - Quality assessment is most valuable as a **trend** — individual snapshots matter less than improvement direction over time. - The maintainability index is a composite heuristic — it provides a single number for quick assessment but the component metrics offer more actionable insights. diff --git a/.claude/skills/pair-capability-assess-debt/SKILL.md b/.claude/skills/pair-capability-assess-debt/SKILL.md index d877bf9d..0cd963b1 100644 --- a/.claude/skills/pair-capability-assess-debt/SKILL.md +++ b/.claude/skills/pair-capability-assess-debt/SKILL.md @@ -18,7 +18,7 @@ Detect, categorize, and prioritize technical debt items. Applies the prioritizat ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. It never auto-creates tech-debt items. A debt item worth scheduling is promoted **deliberately** to the backlog by a human/agent via `/pair-capability-write-issue` with the `tech-debt` label (see [Composition Interface](#composition-interface)) — a manual, selective act, never a 100% auto-conversion. +This skill is **output-only** — it composes no skill and writes no files. No auto-creation of tech-debt items. A debt item worth scheduling is promoted **deliberately** to the backlog by a human/agent via `/pair-capability-write-issue` with the `tech-debt` label (see [Composition Interface](#composition-interface)) — a manual, selective act, never a 100% auto-conversion. ## Algorithm @@ -182,7 +182,6 @@ When invoked **independently**: - Full interactive flow. Scan codebase or specified scope for debt. - Report findings with categorization and prioritization. -- This skill is **output-only** — it inspects code but writes no files, creates no issues, and blocks nothing. Promotion to the backlog is a separate, deliberate `/pair-capability-write-issue` action. ## Graceful Degradation @@ -193,9 +192,6 @@ When invoked **independently**: ## Notes -- This skill **replaces the stub implementation** from [#100](https://github.com/foomakers/pair/issues/100). Full categorization, prioritization formula, and remediation recommendations are now included. -- **Resolution cascade**: Path A (pre-identified item) → Path B (existing assessment) → Path C (full scan). Follows the same pattern as other assess-* skills. - **Idempotent**: re-invocation on an already-assessed codebase confirms the existing assessment. Re-assessment only on explicit developer request. -- **Output-only** — this skill inspects code but never modifies files, adoption, or the PM tool. There is no `$mode:scan` and no auto-creation of tech-debt items (R7.2). Debt is surfaced in the report; promotion to the backlog is a deliberate `/pair-capability-write-issue` act with the `tech-debt` label. - Prioritization formula `Impact × (6 - Effort)` favors quick wins: high-impact items with low effort get the highest scores. - Debt is contextual — the same pattern may be acceptable in a prototype but unacceptable in production code. Severity assessment considers the project's maturity and risk tolerance. diff --git a/.claude/skills/pair-capability-assess-infrastructure/SKILL.md b/.claude/skills/pair-capability-assess-infrastructure/SKILL.md index 1f9895ec..16e69185 100644 --- a/.claude/skills/pair-capability-assess-infrastructure/SKILL.md +++ b/.claude/skills/pair-capability-assess-infrastructure/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend infrastructure strategy: cloud provider, CI/CD pipeline, ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -87,7 +87,7 @@ The rendered adoption content is destined for this file — the caller writes it 1. **Act**: Render the infrastructure.md content — the ready-to-write body for the target file: - Concise, prescriptive statements - Scope to the core infrastructure sections so the caller's write preserves the observability section (owned by /pair-capability-assess-observability) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal diff --git a/.claude/skills/pair-capability-assess-methodology/SKILL.md b/.claude/skills/pair-capability-assess-methodology/SKILL.md index 2d9d9ca3..90e7f57f 100644 --- a/.claude/skills/pair-capability-assess-methodology/SKILL.md +++ b/.claude/skills/pair-capability-assess-methodology/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend the development methodology: Scrum, Kanban, Lean, Waterfa ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -92,7 +92,7 @@ The rendered adoption content is destined for this section — the caller writes - Methodology name and key practices - Development cycle description (iterations, flow, etc.) - Scope strictly to the methodology section so the caller's write preserves all other sections (quality gates, PM tool, etc.) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal diff --git a/.claude/skills/pair-capability-assess-observability/SKILL.md b/.claude/skills/pair-capability-assess-observability/SKILL.md index ce10b377..1da7dee5 100644 --- a/.claude/skills/pair-capability-assess-observability/SKILL.md +++ b/.claude/skills/pair-capability-assess-observability/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend the observability strategy: monitoring platform, logging ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -90,7 +90,7 @@ The rendered adoption content is destined for this section — the caller writes 1. **Act**: Render the **observability section** content — the ready-to-write body for infrastructure.md: - Platform, logging, tracing, alerting decisions - Scope strictly to the observability section so the caller's write preserves all other sections (owned by /pair-capability-assess-infrastructure) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal diff --git a/.claude/skills/pair-capability-assess-pm/SKILL.md b/.claude/skills/pair-capability-assess-pm/SKILL.md index 8e51e374..06411d4c 100644 --- a/.claude/skills/pair-capability-assess-pm/SKILL.md +++ b/.claude/skills/pair-capability-assess-pm/SKILL.md @@ -95,7 +95,7 @@ The rendered adoption content is destined for this section — the caller (or `/ - Workflow methodology integration - Access method (MCP, CLI, filesystem) - Scope strictly to the PM tool section so the caller's write preserves all other sections -4. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +4. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal (only if /pair-capability-setup-pm not invoked) @@ -148,5 +148,5 @@ When invoked **independently**: - PM tool decisions are **non-architectural** → the caller records them as an ADL. - **Section ownership**: this skill renders content ONLY for the PM tool section of way-of-working.md. The single adoption writer is `/pair-capability-record-decision` (or `/pair-capability-setup-pm` when it handles configuration). -- **Delegation pattern**: /pair-capability-assess-pm decides WHICH tool, /pair-capability-setup-pm configures it. If /pair-capability-setup-pm is installed, it handles both adoption write and decision recording; assess-pm itself never writes adoption. +- **Delegation pattern**: /pair-capability-assess-pm decides WHICH tool, /pair-capability-setup-pm configures it — handling both adoption write and decision recording when installed. - Educational content (tool descriptions, integration details) stays in guidelines. diff --git a/.claude/skills/pair-capability-assess-stack/SKILL.md b/.claude/skills/pair-capability-assess-stack/SKILL.md index 4d8d927d..782b39ea 100644 --- a/.claude/skills/pair-capability-assess-stack/SKILL.md +++ b/.claude/skills/pair-capability-assess-stack/SKILL.md @@ -18,7 +18,7 @@ Evaluate and recommend the technology stack: languages, frameworks, runtime, dat ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -171,7 +171,7 @@ Detect and evaluate unlisted dependencies. Used when `/pair-process-review` find 1. **Act** (bootstrap mode): Render full tech-stack.md content with all core sections. Include version for every entry. 2. **Act** (implementation/review mode): Render the affected-entry content for the appropriate section, scoped so the caller's write preserves all other content, including sections owned by /pair-capability-assess-testing and /pair-capability-assess-ai. -3. **Verify**: The rendered `content` and its `target` are ready to emit. All entries have versions; section ownership respected. **This skill writes no files.** +3. **Verify**: The rendered `content` and its `target` are ready to emit. All entries have versions; section ownership respected. ### Step 5: Emit Proposal @@ -259,8 +259,6 @@ When invoked **independently**: ## Notes -- **Lifecycle-spanning**: unlike other assess-* skills (primarily bootstrap), /pair-capability-assess-stack is used throughout bootstrap, implementation, and review. - **Tech stack as registry**: `tech-stack.md` is the registry of approved technologies. Only listed technologies are approved. Unlisted technologies detected during review trigger /pair-capability-assess-stack evaluation. - Stack decisions are typically **non-architectural** → the caller records them as an ADL. Exception: if a stack choice fundamentally changes the architecture (e.g. switching from monolith to microservices runtime), the caller uses ADR. -- **Section ownership** keeps proposals non-overlapping: each assess-* skill renders only its sections; the single adoption writer is `/pair-capability-record-decision`, which preserves others on write. - Educational content (technology descriptions, ecosystem overview, WHY) stays in guidelines. This skill references guidelines for evaluation criteria and comparison matrices. diff --git a/.claude/skills/pair-capability-assess-testing/SKILL.md b/.claude/skills/pair-capability-assess-testing/SKILL.md index 0bfa8045..bf41397d 100644 --- a/.claude/skills/pair-capability-assess-testing/SKILL.md +++ b/.claude/skills/pair-capability-assess-testing/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend the testing strategy: framework, pyramid distribution, co ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -108,7 +108,7 @@ The rendered adoption content is destined for this section — the caller writes - Coverage tool and version - Additional testing tools with versions - Scope strictly to the Testing section so the caller's write preserves all other sections (core, AI, etc.) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal @@ -142,7 +142,7 @@ When composed by `/pair-process-bootstrap`: When invoked **independently**: -- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits the changes. +- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits. ## Edge Cases @@ -161,7 +161,7 @@ When invoked **independently**: ## Notes - Testing decisions are typically **non-architectural** → the caller records them as an ADL. Exception: if the testing strategy choice affects system structure (e.g. choosing contract testing that requires service boundaries), the caller uses ADR instead. -- **Section ownership**: this skill renders content ONLY for the Testing section of tech-stack.md. /pair-capability-assess-stack owns core sections, /pair-capability-assess-ai owns AI section. The single adoption writer is `/pair-capability-record-decision`. +- **Section ownership**: this skill renders content ONLY for the Testing section of tech-stack.md. The single adoption writer is `/pair-capability-record-decision`. - Version tracking: every testing tool includes specific version. - The resolution cascade IS the idempotency mechanism: if testing section is populated, assessment is already done. - Educational content (testing philosophy, principles, WHY) stays in guidelines. This skill references guidelines for framework comparison and strategy decisions. diff --git a/.claude/skills/pair-capability-record-decision/SKILL.md b/.claude/skills/pair-capability-record-decision/SKILL.md index 1166efff..706a7dd6 100644 --- a/.claude/skills/pair-capability-record-decision/SKILL.md +++ b/.claude/skills/pair-capability-record-decision/SKILL.md @@ -9,7 +9,7 @@ author: Foomakers Record a decision as an ADR (architectural), ADL (non-architectural), or DDR (domain). Always update the corresponding adoption files — or, for DDR, the context map — to keep them as the single source of truth for "what we use now." -This skill is the **sole generic writer of adoption files** (assess-* are output-only and delegate persistence here); the one exception is `/setup-pm`, which owns PM-tool configuration end-to-end — it writes the PM section of `way-of-working.md` itself, then composes this skill only for the decision record. When a caller supplies pre-rendered `$content` and a `$target`, this skill acts as a **generic persister** — it writes `$content` into its owned section of `$target` (a heading-scoped merge) and records the decision, with **no per-domain rendering logic** (each `assess-*` knows how to render its own adoption content; this skill only persists it). +This skill is the **sole generic writer of adoption files** (assess-* are output-only and delegate persistence here); the one exception is `/setup-pm`, which owns PM-tool configuration end-to-end — it writes the PM section of `way-of-working.md` itself, then composes this skill only for the decision record. When a caller supplies pre-rendered `$content` and a `$target`, this skill acts as a **generic persister** — it writes `$content` into its owned section of `$target` (a heading-scoped merge) and records the decision, with **no per-domain rendering logic**. ## Arguments @@ -102,7 +102,7 @@ A domain decision only becomes a DDR if it meets **all three** criteria. This is ### Step 4: Update Adoption Files or Context Map -This step is **always required** — adoption files and the context map are the single source of truth. This skill is the sole generic writer of adoption files; the one exception is `/setup-pm` for the PM-tool section of way-of-working.md (see the overview). +This step is **always required** — adoption files and the context map are the single source of truth. #### If `$content` and `$target` provided → Generic Persist (assess-* proposal): @@ -160,7 +160,7 @@ When composed by `/pair-process-implement` or `/pair-process-review`: When composed by `/pair-process-bootstrap` or an `assess-*` proposal (generic persist): - **Input**: The caller passes `$content` (the rendered adoption body from an `assess-*` skill) and `$target` (the adoption file/section), plus `$type`, `$topic`, `$summary`. -- **Output**: This skill writes `$content` into its owned section of `$target` (a heading-scoped merge) and records the ADR/ADL — it is the **sole generic adoption writer**. It performs no per-domain rendering; the assess-* skill owns the content. +- **Output**: This skill writes `$content` into its owned section of `$target` (a heading-scoped merge) and records the ADR/ADL. It performs no per-domain rendering; the assess-* skill owns the content. - This keeps the invariant: **only `record-decision` writes adoption files generically** (the sole exception is `/setup-pm`, which writes the PM section of `way-of-working.md` directly); **only assess-* renders** its own adoption content; the caller orchestrates the two. When invoked **independently**: @@ -184,12 +184,9 @@ When invoked **independently**: - If [ADL template](../../../.pair/knowledge/guidelines/collaboration/templates/adl-template.md) is not found, use the minimal ADL structure: Date, Status, Context, Decision, Consequences, Adoption Impact. - If [DDR template](../../../.pair/knowledge/guidelines/collaboration/templates/ddr-template.md) is not found, use the minimal DDR structure: Status, Date, Context, Decision, Consequences, Context Map Impact. - If adoption directories don't exist, create them and warn: "Created adoption directory — this appears to be a new project." -- If neither `context-map.md` nor a matching `.context.md` exists for a DDR, offer to create a minimal `context-map.md` containing just the affected rule/term — warn the developer this is the project's first domain-context artifact. ## Notes -- ADR, ADL, and DDR are mutually exclusive. Never write more than one for the same decision. -- Adoption files (ADR/ADL) and the context map (DDR) are always updated. A decision without that sync is incomplete. - Date-based naming (`YYYY-MM-DD-`) ensures ADL sortability; sequential naming (`adr-NNN-`/`ddr-NNN-`) makes ADR and DDR supersede chains and cross-references (e.g., brainstorm conflict flags) easy to cite by number. - The DDR criteria gate (Step 1b) exists to keep `adoption/product/ddr/` reserved for decisions worth their own historical record — everything else is an ADL or an inline note. - This skill modifies files: decision files and adoption files, or the context map. All changes should be committed together. diff --git a/.claude/skills/pair-capability-write-issue/SKILL.md b/.claude/skills/pair-capability-write-issue/SKILL.md index eb9475e3..e2cdc668 100644 --- a/.claude/skills/pair-capability-write-issue/SKILL.md +++ b/.claude/skills/pair-capability-write-issue/SKILL.md @@ -200,8 +200,7 @@ This skill supports `story`, `task`, `epic`, and `initiative` types. Adding a ne ## Notes - This skill **modifies PM tool state** — it creates and updates issues. -- No PM tool fallback: if the adopted tool fails, the skill HALTs. The developer resolves the issue, then re-invokes (idempotent by design — `$id` prevents duplicate creation). +- No PM tool fallback: if the adopted tool fails, the skill HALTs — re-invocation is idempotent (`$id` prevents duplicate creation). - Template = source of truth for issue body format. Changes to template structure automatically affect all future issue creation. - Labels and hierarchy linking follow the PM tool implementation guide conventions. - **Deliberate tech-debt promotion**: assess-* skills are output-only and never auto-create backlog items. When a debt or quality finding is worth scheduling, a human/agent promotes it here **deliberately** by passing `tech-debt` in `$labels` — a manual, selective act, never a 100% auto-conversion (R7.2). -- State resolution: `$status` is always a canonical macrostate — never a board-specific label. See [canonical-states.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/canonical-states.md). diff --git a/.claude/skills/pair-process-bootstrap/SKILL.md b/.claude/skills/pair-process-bootstrap/SKILL.md index ad95d1aa..9b9dee6a 100644 --- a/.claude/skills/pair-process-bootstrap/SKILL.md +++ b/.claude/skills/pair-process-bootstrap/SKILL.md @@ -111,7 +111,7 @@ Orchestrate the complete project setup sequence. Transforms a PRD into a fully c 7. `/pair-capability-assess-methodology` → proposes methodology section of `way-of-working.md` 8. `/pair-capability-assess-pm` → proposes PM section of `way-of-working.md` (delegates to `/pair-capability-setup-pm` when installed) - After each assessment (or after collecting the batch), compose `/pair-capability-record-decision(content, target, decision-metadata)` to persist the proposal to its target adoption file and record the ADR/ADL. `/pair-capability-assess-pm` persists via `/pair-capability-setup-pm` when that skill is installed; otherwise `/pair-process-bootstrap` persists its proposal via `/pair-capability-record-decision` like the others. + After each assessment (or after collecting the batch), compose `/pair-capability-record-decision(content, target, decision-metadata)` to persist the proposal and record the ADR/ADL. `/pair-capability-assess-pm` persists via `/pair-capability-setup-pm` when that skill is installed; otherwise `/pair-process-bootstrap` persists its proposal via `/pair-capability-record-decision` like the others. **Section ownership** (each assess-\* proposal owns its section; `/pair-capability-record-decision` preserves the rest on write): @@ -307,10 +307,6 @@ Phase completion is detected via output file existence — never re-does complet ## Notes -- This is the most complex process skill — it orchestrates the full project setup sequence. -- Each phase is independent: completion of one phase doesn't require re-running previous phases. -- The developer can stop between phases. Re-invoke to resume (idempotency ensures correct state). -- All decisions during bootstrap are recorded via `/pair-capability-record-decision`. Non-architectural → ADL. Architectural → ADR. -- Quality gate setup ensures the gate infrastructure is executable from day one (not deferred to first implementation). +- The developer can stop between phases; re-invoke to resume (idempotency ensures correct state). - Phase 3.5 is the only full-catalog (`$scope: all`) entry point for `/pair-capability-map-subdomains` and `/pair-capability-map-contexts` — every other caller is scoped to what it just touched. See [Callers Matrix](../../../.pair/knowledge/skills-guide.md#callers-matrix-scoped-capabilities). - Content source: how-to-02 Phases 0-4 (including domain modeling). How-to-02 retains orchestration flow, this skill has operational detail. diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 2a246191..60469075 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -17,8 +17,8 @@ Review a pull request through 6 sequential phases (5 review + 1 optional merge). | `/pair-capability-verify-done` | Capability | Yes | 4 | Definition of Done checking | | `/pair-capability-record-decision` | Capability | Yes | Any | Record missing ADR (HALT condition) | | `/pair-capability-assess-debt` | Capability | Yes | 4 | Flag tech debt items | -| `/pair-capability-verify-adoption` | Capability | Optional | 3 | Full adoption compliance (from #105) | -| `/pair-capability-assess-stack` | Capability | Optional | 3 | Tech-stack resolution (from #104) | +| `/pair-capability-verify-adoption` | Capability | Optional | 3 | Full adoption compliance | +| `/pair-capability-assess-stack` | Capability | Optional | 3 | Tech-stack resolution | | `/pair-capability-execute-manual-tests` | Capability | Optional | 6 | Post-merge release validation (manual tests) | ## Arguments @@ -384,10 +384,8 @@ Re-invoking `/pair-process-review` on a partially reviewed PR is safe: ## Notes - This skill **reads code, posts review comments, and optionally merges PRs** — it does not modify source code. -- First skill to compose 7 atomic skills (4 required + 3 optional). Proves composition pattern at scale. - Review phases are sequential — each phase builds on findings from prior phases. -- The reviewer can stop between phases. Re-invoke to resume (idempotency ensures correct state). +- The reviewer can stop between phases; re-invoke to resume (idempotency ensures correct state). - Output follows [code-review-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/code-review-template.md) — the template defines structure, /pair-process-review fills it with findings. - HALT on missing ADR is inherited from [how-to-11](../../../.pair/knowledge/how-to/11-how-to-code-review.md) — this is a business rule, not a skill limitation. -- **Phase 6 is optional** — the reviewer can stop after Phase 5. The author can alternatively merge via `/pair-process-implement` Phase 4. - **Parent cascade is best-effort** — if sub-issue queries fail, the skill reports which updates need manual attention. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md index bf1f6693..dcc37f65 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend AI development tools: AI assistants, MCP integrations, AI ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -97,7 +97,7 @@ The rendered adoption content is destined for this section — the caller writes - MCP integrations if applicable - AI-specific SDKs and libraries with versions - Scope strictly to the AI section so the caller's write preserves all other sections (core, testing) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md index a9191ed3..5955aaf9 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend the system architecture pattern. Follows the resolution c ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -98,7 +98,7 @@ The rendered adoption content is destined for this file — the caller writes it - Concise, prescriptive statements (what IS adopted, not options) - Reference guidelines for detailed rationale - Scope the content to this skill's owned section so the caller's write preserves other sections -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal @@ -107,7 +107,7 @@ The rendered adoption content is destined for this file — the caller writes it - `target`: [adoption/tech/architecture.md](../../../.pair/adoption/tech/architecture.md) (owned section) - `decision-metadata`: `$type: architectural`, `$topic: architecture-pattern`, `$summary: "[Pattern] adopted as system architecture"` - plus the human-facing report (see Output Format) -2. **Verify**: Proposal emitted. Persistence — writing `content` to `target` and recording the ADR — is performed by the caller via `/record-decision(content, target, decision-metadata)`, never by this skill. +2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/record-decision(content, target, decision-metadata)`, never by this skill. ## Output Format @@ -132,7 +132,7 @@ When composed by `/bootstrap`: When invoked **independently**: -- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits the changes. +- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. ## Edge Cases diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-code-quality/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-code-quality/SKILL.md index 80b3c250..256550ae 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-code-quality/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-code-quality/SKILL.md @@ -45,7 +45,7 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p - Size metrics: lines of code, function length, class/module size, file size - Quality metrics: test coverage, code duplication, maintainability index - Thresholds per metric (e.g., cyclomatic complexity 1-5 = simple, 16+ = refactor needed) -2. **Verify**: Guidelines loaded. If not found, use built-in thresholds. +2. **Verify**: Guidelines loaded. ### Step 3: Collect Metrics @@ -149,7 +149,6 @@ When composed by `/review`: When invoked **independently**: - Full interactive flow. Developer receives the report and decides on improvement actions. -- This skill is **read-only** — it inspects code and runs tests (coverage) but does not modify files. ## Graceful Degradation @@ -162,7 +161,6 @@ When invoked **independently**: - This skill is **read-only / output-only** — it inspects code, runs coverage (via existing test commands), but never modifies files, adoption, or the PM tool. A finding worth tracking is promoted deliberately to the backlog via `/write-issue` (a manual, selective act) — never auto-created. - **Idempotent**: re-invocation checks staleness of existing report. If codebase unchanged → confirms existing report. If changed → re-assesses only. -- **Resolution cascade**: Path A (existing recent report) → Path B (full assessment). Follows the same cascade pattern as other assess-* skills. - Metrics are **health indicators, not absolute quality measures**. Context matters: business logic naturally has higher complexity, and metric targets should align with team capabilities. - Quality assessment is most valuable as a **trend** — individual snapshots matter less than improvement direction over time. - The maintainability index is a composite heuristic — it provides a single number for quick assessment but the component metrics offer more actionable insights. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md index 41edd342..9ba8c526 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md @@ -18,7 +18,7 @@ Detect, categorize, and prioritize technical debt items. Applies the prioritizat ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. It never auto-creates tech-debt items. A debt item worth scheduling is promoted **deliberately** to the backlog by a human/agent via `/write-issue` with the `tech-debt` label (see [Composition Interface](#composition-interface)) — a manual, selective act, never a 100% auto-conversion. +This skill is **output-only** — it composes no skill and writes no files. No auto-creation of tech-debt items. A debt item worth scheduling is promoted **deliberately** to the backlog by a human/agent via `/write-issue` with the `tech-debt` label (see [Composition Interface](#composition-interface)) — a manual, selective act, never a 100% auto-conversion. ## Algorithm @@ -182,7 +182,6 @@ When invoked **independently**: - Full interactive flow. Scan codebase or specified scope for debt. - Report findings with categorization and prioritization. -- This skill is **output-only** — it inspects code but writes no files, creates no issues, and blocks nothing. Promotion to the backlog is a separate, deliberate `/write-issue` action. ## Graceful Degradation @@ -193,9 +192,6 @@ When invoked **independently**: ## Notes -- This skill **replaces the stub implementation** from [#100](https://github.com/foomakers/pair/issues/100). Full categorization, prioritization formula, and remediation recommendations are now included. -- **Resolution cascade**: Path A (pre-identified item) → Path B (existing assessment) → Path C (full scan). Follows the same pattern as other assess-* skills. - **Idempotent**: re-invocation on an already-assessed codebase confirms the existing assessment. Re-assessment only on explicit developer request. -- **Output-only** — this skill inspects code but never modifies files, adoption, or the PM tool. There is no `$mode:scan` and no auto-creation of tech-debt items (R7.2). Debt is surfaced in the report; promotion to the backlog is a deliberate `/write-issue` act with the `tech-debt` label. - Prioritization formula `Impact × (6 - Effort)` favors quick wins: high-impact items with low effort get the highest scores. - Debt is contextual — the same pattern may be acceptable in a prototype but unacceptable in production code. Severity assessment considers the project's maturity and risk tolerance. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md index 7c652e4d..169847ab 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend infrastructure strategy: cloud provider, CI/CD pipeline, ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -87,7 +87,7 @@ The rendered adoption content is destined for this file — the caller writes it 1. **Act**: Render the infrastructure.md content — the ready-to-write body for the target file: - Concise, prescriptive statements - Scope to the core infrastructure sections so the caller's write preserves the observability section (owned by /assess-observability) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md index d0a8b44f..48bbfd8c 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend the development methodology: Scrum, Kanban, Lean, Waterfa ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -92,7 +92,7 @@ The rendered adoption content is destined for this section — the caller writes - Methodology name and key practices - Development cycle description (iterations, flow, etc.) - Scope strictly to the methodology section so the caller's write preserves all other sections (quality gates, PM tool, etc.) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md index d34bf5f4..1d8438b5 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend the observability strategy: monitoring platform, logging ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -90,7 +90,7 @@ The rendered adoption content is destined for this section — the caller writes 1. **Act**: Render the **observability section** content — the ready-to-write body for infrastructure.md: - Platform, logging, tracing, alerting decisions - Scope strictly to the observability section so the caller's write preserves all other sections (owned by /assess-infrastructure) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md index 5b29888e..1bf73ea4 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md @@ -95,7 +95,7 @@ The rendered adoption content is destined for this section — the caller (or `/ - Workflow methodology integration - Access method (MCP, CLI, filesystem) - Scope strictly to the PM tool section so the caller's write preserves all other sections -4. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +4. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal (only if /setup-pm not invoked) @@ -148,5 +148,5 @@ When invoked **independently**: - PM tool decisions are **non-architectural** → the caller records them as an ADL. - **Section ownership**: this skill renders content ONLY for the PM tool section of way-of-working.md. The single adoption writer is `/record-decision` (or `/setup-pm` when it handles configuration). -- **Delegation pattern**: /assess-pm decides WHICH tool, /setup-pm configures it. If /setup-pm is installed, it handles both adoption write and decision recording; assess-pm itself never writes adoption. +- **Delegation pattern**: /assess-pm decides WHICH tool, /setup-pm configures it — handling both adoption write and decision recording when installed. - Educational content (tool descriptions, integration details) stays in guidelines. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md index 5d863179..83402c85 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md @@ -18,7 +18,7 @@ Evaluate and recommend the technology stack: languages, frameworks, runtime, dat ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -171,7 +171,7 @@ Detect and evaluate unlisted dependencies. Used when `/review` finds a dependenc 1. **Act** (bootstrap mode): Render full tech-stack.md content with all core sections. Include version for every entry. 2. **Act** (implementation/review mode): Render the affected-entry content for the appropriate section, scoped so the caller's write preserves all other content, including sections owned by /assess-testing and /assess-ai. -3. **Verify**: The rendered `content` and its `target` are ready to emit. All entries have versions; section ownership respected. **This skill writes no files.** +3. **Verify**: The rendered `content` and its `target` are ready to emit. All entries have versions; section ownership respected. ### Step 5: Emit Proposal @@ -259,8 +259,6 @@ When invoked **independently**: ## Notes -- **Lifecycle-spanning**: unlike other assess-* skills (primarily bootstrap), /assess-stack is used throughout bootstrap, implementation, and review. - **Tech stack as registry**: `tech-stack.md` is the registry of approved technologies. Only listed technologies are approved. Unlisted technologies detected during review trigger /assess-stack evaluation. - Stack decisions are typically **non-architectural** → the caller records them as an ADL. Exception: if a stack choice fundamentally changes the architecture (e.g. switching from monolith to microservices runtime), the caller uses ADR. -- **Section ownership** keeps proposals non-overlapping: each assess-* skill renders only its sections; the single adoption writer is `/record-decision`, which preserves others on write. - Educational content (technology descriptions, ecosystem overview, WHY) stays in guidelines. This skill references guidelines for evaluation criteria and comparison matrices. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md index 560c18bf..bb2a49b1 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md @@ -17,7 +17,7 @@ Evaluate and recommend the testing strategy: framework, pyramid distribution, co ## Composed Skills -This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/record-decision` (see [Composition Interface](#composition-interface)). +**Output-only** — composes no skill, writes no files; the caller persists via `/record-decision` (see [Composition Interface](#composition-interface)). ## Proposal Target @@ -108,7 +108,7 @@ The rendered adoption content is destined for this section — the caller writes - Coverage tool and version - Additional testing tools with versions - Scope strictly to the Testing section so the caller's write preserves all other sections (core, AI, etc.) -2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.** +2. **Verify**: The rendered `content` and its `target` are ready to emit. ### Step 5: Emit Proposal @@ -142,7 +142,7 @@ When composed by `/bootstrap`: When invoked **independently**: -- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits the changes. +- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. ## Edge Cases @@ -161,7 +161,7 @@ When invoked **independently**: ## Notes - Testing decisions are typically **non-architectural** → the caller records them as an ADL. Exception: if the testing strategy choice affects system structure (e.g. choosing contract testing that requires service boundaries), the caller uses ADR instead. -- **Section ownership**: this skill renders content ONLY for the Testing section of tech-stack.md. /assess-stack owns core sections, /assess-ai owns AI section. The single adoption writer is `/record-decision`. +- **Section ownership**: this skill renders content ONLY for the Testing section of tech-stack.md. The single adoption writer is `/record-decision`. - Version tracking: every testing tool includes specific version. - The resolution cascade IS the idempotency mechanism: if testing section is populated, assessment is already done. - Educational content (testing philosophy, principles, WHY) stays in guidelines. This skill references guidelines for framework comparison and strategy decisions. diff --git a/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md index fdfe0a11..1841fad4 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md @@ -9,7 +9,7 @@ author: Foomakers Record a decision as an ADR (architectural), ADL (non-architectural), or DDR (domain). Always update the corresponding adoption files — or, for DDR, the context map — to keep them as the single source of truth for "what we use now." -This skill is the **sole generic writer of adoption files** (assess-* are output-only and delegate persistence here); the one exception is `/setup-pm`, which owns PM-tool configuration end-to-end — it writes the PM section of `way-of-working.md` itself, then composes this skill only for the decision record. When a caller supplies pre-rendered `$content` and a `$target`, this skill acts as a **generic persister** — it writes `$content` into its owned section of `$target` (a heading-scoped merge) and records the decision, with **no per-domain rendering logic** (each `assess-*` knows how to render its own adoption content; this skill only persists it). +This skill is the **sole generic writer of adoption files** (assess-* are output-only and delegate persistence here); the one exception is `/setup-pm`, which owns PM-tool configuration end-to-end — it writes the PM section of `way-of-working.md` itself, then composes this skill only for the decision record. When a caller supplies pre-rendered `$content` and a `$target`, this skill acts as a **generic persister** — it writes `$content` into its owned section of `$target` (a heading-scoped merge) and records the decision, with **no per-domain rendering logic**. ## Arguments @@ -102,7 +102,7 @@ A domain decision only becomes a DDR if it meets **all three** criteria. This is ### Step 4: Update Adoption Files or Context Map -This step is **always required** — adoption files and the context map are the single source of truth. This skill is the sole generic writer of adoption files; the one exception is `/setup-pm` for the PM-tool section of way-of-working.md (see the overview). +This step is **always required** — adoption files and the context map are the single source of truth. #### If `$content` and `$target` provided → Generic Persist (assess-* proposal): @@ -160,7 +160,7 @@ When composed by `/implement` or `/review`: When composed by `/bootstrap` or an `assess-*` proposal (generic persist): - **Input**: The caller passes `$content` (the rendered adoption body from an `assess-*` skill) and `$target` (the adoption file/section), plus `$type`, `$topic`, `$summary`. -- **Output**: This skill writes `$content` into its owned section of `$target` (a heading-scoped merge) and records the ADR/ADL — it is the **sole generic adoption writer**. It performs no per-domain rendering; the assess-* skill owns the content. +- **Output**: This skill writes `$content` into its owned section of `$target` (a heading-scoped merge) and records the ADR/ADL. It performs no per-domain rendering; the assess-* skill owns the content. - This keeps the invariant: **only `record-decision` writes adoption files generically** (the sole exception is `/setup-pm`, which writes the PM section of `way-of-working.md` directly); **only assess-* renders** its own adoption content; the caller orchestrates the two. When invoked **independently**: @@ -184,12 +184,9 @@ When invoked **independently**: - If [ADL template](../../../.pair/knowledge/guidelines/collaboration/templates/adl-template.md) is not found, use the minimal ADL structure: Date, Status, Context, Decision, Consequences, Adoption Impact. - If [DDR template](../../../.pair/knowledge/guidelines/collaboration/templates/ddr-template.md) is not found, use the minimal DDR structure: Status, Date, Context, Decision, Consequences, Context Map Impact. - If adoption directories don't exist, create them and warn: "Created adoption directory — this appears to be a new project." -- If neither `context-map.md` nor a matching `.context.md` exists for a DDR, offer to create a minimal `context-map.md` containing just the affected rule/term — warn the developer this is the project's first domain-context artifact. ## Notes -- ADR, ADL, and DDR are mutually exclusive. Never write more than one for the same decision. -- Adoption files (ADR/ADL) and the context map (DDR) are always updated. A decision without that sync is incomplete. - Date-based naming (`YYYY-MM-DD-`) ensures ADL sortability; sequential naming (`adr-NNN-`/`ddr-NNN-`) makes ADR and DDR supersede chains and cross-references (e.g., brainstorm conflict flags) easy to cite by number. - The DDR criteria gate (Step 1b) exists to keep `adoption/product/ddr/` reserved for decisions worth their own historical record — everything else is an ADL or an inline note. - This skill modifies files: decision files and adoption files, or the context map. All changes should be committed together. diff --git a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md index e0150891..694d9f97 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md @@ -200,8 +200,7 @@ This skill supports `story`, `task`, `epic`, and `initiative` types. Adding a ne ## Notes - This skill **modifies PM tool state** — it creates and updates issues. -- No PM tool fallback: if the adopted tool fails, the skill HALTs. The developer resolves the issue, then re-invokes (idempotent by design — `$id` prevents duplicate creation). +- No PM tool fallback: if the adopted tool fails, the skill HALTs — re-invocation is idempotent (`$id` prevents duplicate creation). - Template = source of truth for issue body format. Changes to template structure automatically affect all future issue creation. - Labels and hierarchy linking follow the PM tool implementation guide conventions. - **Deliberate tech-debt promotion**: assess-* skills are output-only and never auto-create backlog items. When a debt or quality finding is worth scheduling, a human/agent promotes it here **deliberately** by passing `tech-debt` in `$labels` — a manual, selective act, never a 100% auto-conversion (R7.2). -- State resolution: `$status` is always a canonical macrostate — never a board-specific label. See [canonical-states.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/canonical-states.md). diff --git a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md index e2468b0a..7f0b8891 100644 --- a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md @@ -111,7 +111,7 @@ Orchestrate the complete project setup sequence. Transforms a PRD into a fully c 7. `/assess-methodology` → proposes methodology section of `way-of-working.md` 8. `/assess-pm` → proposes PM section of `way-of-working.md` (delegates to `/setup-pm` when installed) - After each assessment (or after collecting the batch), compose `/record-decision(content, target, decision-metadata)` to persist the proposal to its target adoption file and record the ADR/ADL. `/assess-pm` persists via `/setup-pm` when that skill is installed; otherwise `/bootstrap` persists its proposal via `/record-decision` like the others. + After each assessment (or after collecting the batch), compose `/record-decision(content, target, decision-metadata)` to persist the proposal and record the ADR/ADL. `/assess-pm` persists via `/setup-pm` when that skill is installed; otherwise `/bootstrap` persists its proposal via `/record-decision` like the others. **Section ownership** (each assess-\* proposal owns its section; `/record-decision` preserves the rest on write): @@ -307,10 +307,6 @@ Phase completion is detected via output file existence — never re-does complet ## Notes -- This is the most complex process skill — it orchestrates the full project setup sequence. -- Each phase is independent: completion of one phase doesn't require re-running previous phases. -- The developer can stop between phases. Re-invoke to resume (idempotency ensures correct state). -- All decisions during bootstrap are recorded via `/record-decision`. Non-architectural → ADL. Architectural → ADR. -- Quality gate setup ensures the gate infrastructure is executable from day one (not deferred to first implementation). +- The developer can stop between phases; re-invoke to resume (idempotency ensures correct state). - Phase 3.5 is the only full-catalog (`$scope: all`) entry point for `/map-subdomains` and `/map-contexts` — every other caller is scoped to what it just touched. See [Callers Matrix](../../../.pair/knowledge/skills-guide.md#callers-matrix-scoped-capabilities). - Content source: how-to-02 Phases 0-4 (including domain modeling). How-to-02 retains orchestration flow, this skill has operational detail. diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index 6ce24c6f..3e59f5df 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -17,8 +17,8 @@ Review a pull request through 6 sequential phases (5 review + 1 optional merge). | `/verify-done` | Capability | Yes | 4 | Definition of Done checking | | `/record-decision` | Capability | Yes | Any | Record missing ADR (HALT condition) | | `/assess-debt` | Capability | Yes | 4 | Flag tech debt items | -| `/verify-adoption` | Capability | Optional | 3 | Full adoption compliance (from #105) | -| `/assess-stack` | Capability | Optional | 3 | Tech-stack resolution (from #104) | +| `/verify-adoption` | Capability | Optional | 3 | Full adoption compliance | +| `/assess-stack` | Capability | Optional | 3 | Tech-stack resolution | | `/execute-manual-tests` | Capability | Optional | 6 | Post-merge release validation (manual tests) | ## Arguments @@ -384,10 +384,8 @@ Re-invoking `/review` on a partially reviewed PR is safe: ## Notes - This skill **reads code, posts review comments, and optionally merges PRs** — it does not modify source code. -- First skill to compose 7 atomic skills (4 required + 3 optional). Proves composition pattern at scale. - Review phases are sequential — each phase builds on findings from prior phases. -- The reviewer can stop between phases. Re-invoke to resume (idempotency ensures correct state). +- The reviewer can stop between phases; re-invoke to resume (idempotency ensures correct state). - Output follows [code-review-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/code-review-template.md) — the template defines structure, /review fills it with findings. - HALT on missing ADR is inherited from [how-to-11](../../../.pair/knowledge/how-to/11-how-to-code-review.md) — this is a business rule, not a skill limitation. -- **Phase 6 is optional** — the reviewer can stop after Phase 5. The author can alternatively merge via `/implement` Phase 4. - **Parent cascade is best-effort** — if sub-issue queries fail, the skill reports which updates need manual attention. From fea700d7e562ada4330b8fd08b47bcba4af21c1b Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Sun, 12 Jul 2026 20:26:26 +0200 Subject: [PATCH 7/8] [#313] fix: strip repo-specific R7.2 citations from skills (review remediation) Co-Authored-By: Claude Fable 5 --- .claude/skills/pair-capability-assess-debt/SKILL.md | 4 ++-- .claude/skills/pair-capability-write-issue/SKILL.md | 2 +- .claude/skills/pair-process-review/SKILL.md | 2 +- .../dataset/.skills/capability/assess-debt/SKILL.md | 4 ++-- .../dataset/.skills/capability/write-issue/SKILL.md | 2 +- .../knowledge-hub/dataset/.skills/process/review/SKILL.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.claude/skills/pair-capability-assess-debt/SKILL.md b/.claude/skills/pair-capability-assess-debt/SKILL.md index 0cd963b1..e041832a 100644 --- a/.claude/skills/pair-capability-assess-debt/SKILL.md +++ b/.claude/skills/pair-capability-assess-debt/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /pair-capability-assess-debt — Technical Debt Assessment -Detect, categorize, and prioritize technical debt items. Applies the prioritization framework from [technical-debt.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/technical-debt.md) guidelines. Produces a debt report with categorized items, severity, impact/effort scoring, and remediation recommendations. **Output-only**: this skill returns a report — it writes no files, creates no PM-tool items, and there is **no `$mode:scan`** and **no auto-conversion** of debt into backlog cards. Technical debt **never blocks a PR** (R7.2). +Detect, categorize, and prioritize technical debt items. Applies the prioritization framework from [technical-debt.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/technical-debt.md) guidelines. Produces a debt report with categorized items, severity, impact/effort scoring, and remediation recommendations. **Output-only**: this skill returns a report — it writes no files, creates no PM-tool items, and there is **no `$mode:scan`** and **no auto-conversion** of debt into backlog cards. Technical debt **never blocks a PR**. ## Arguments @@ -175,7 +175,7 @@ When composed by `/pair-process-review`: - **Input**: /pair-process-review invokes `/pair-capability-assess-debt` during the completeness phase (Phase 4). - **Output**: Returns the debt assessment report. /pair-process-review incorporates findings into review output (the Tech Debt section). - - Debt items are **informational** — they do **not** HALT the review and **never** block the PR (R7.2). + - Debt items are **informational** — they do **not** HALT the review and **never** block the PR. - /pair-process-review does **not** auto-create tech-debt issues. Items worth tracking are promoted deliberately (after review) via `/pair-capability-write-issue` with the `tech-debt` label. When invoked **independently**: diff --git a/.claude/skills/pair-capability-write-issue/SKILL.md b/.claude/skills/pair-capability-write-issue/SKILL.md index e2cdc668..1a32f9c3 100644 --- a/.claude/skills/pair-capability-write-issue/SKILL.md +++ b/.claude/skills/pair-capability-write-issue/SKILL.md @@ -203,4 +203,4 @@ This skill supports `story`, `task`, `epic`, and `initiative` types. Adding a ne - No PM tool fallback: if the adopted tool fails, the skill HALTs — re-invocation is idempotent (`$id` prevents duplicate creation). - Template = source of truth for issue body format. Changes to template structure automatically affect all future issue creation. - Labels and hierarchy linking follow the PM tool implementation guide conventions. -- **Deliberate tech-debt promotion**: assess-* skills are output-only and never auto-create backlog items. When a debt or quality finding is worth scheduling, a human/agent promotes it here **deliberately** by passing `tech-debt` in `$labels` — a manual, selective act, never a 100% auto-conversion (R7.2). +- **Deliberate tech-debt promotion**: assess-* skills are output-only and never auto-create backlog items. When a debt or quality finding is worth scheduling, a human/agent promotes it here **deliberately** by passing `tech-debt` in `$labels` — a manual, selective act, never a 100% auto-conversion. diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 60469075..cc9acb43 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -194,7 +194,7 @@ This phase uses a **4-level graceful degradation cascade** depending on which op 1. **Check**: Has `/pair-capability-assess-debt` already run in this session? 2. **Skip**: If already run — reuse results, move to Phase 5. 3. **Act**: Compose `/pair-capability-assess-debt` with `$scope = all`. `/pair-capability-assess-debt` is **output-only** — it returns a report and creates nothing. -4. **Act**: Report the debt items in the review output (Tech Debt section). Debt introduced by the PR is **surfaced, not blocked**: it does **not** HALT the review and **never** blocks the PR (R7.2). Do **not** auto-create a tech-debt issue. +4. **Act**: Report the debt items in the review output (Tech Debt section). Debt introduced by the PR is **surfaced, not blocked**: it does **not** HALT the review and **never** blocks the PR. Do **not** auto-create a tech-debt issue. 5. **Act**: If a debt item is worth scheduling, note it as a recommendation for **deliberate** promotion after review via `/pair-capability-write-issue` (with the `tech-debt` label) — a manual, selective act, never automatic. 6. **Verify**: Debt items recorded in the report. High-severity items may inform the review verdict (TECH-DEBT: approve + track separately) but never force CHANGES-REQUESTED on debt grounds alone. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md index 9ba8c526..1b7eef3c 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /assess-debt — Technical Debt Assessment -Detect, categorize, and prioritize technical debt items. Applies the prioritization framework from [technical-debt.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/technical-debt.md) guidelines. Produces a debt report with categorized items, severity, impact/effort scoring, and remediation recommendations. **Output-only**: this skill returns a report — it writes no files, creates no PM-tool items, and there is **no `$mode:scan`** and **no auto-conversion** of debt into backlog cards. Technical debt **never blocks a PR** (R7.2). +Detect, categorize, and prioritize technical debt items. Applies the prioritization framework from [technical-debt.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/technical-debt.md) guidelines. Produces a debt report with categorized items, severity, impact/effort scoring, and remediation recommendations. **Output-only**: this skill returns a report — it writes no files, creates no PM-tool items, and there is **no `$mode:scan`** and **no auto-conversion** of debt into backlog cards. Technical debt **never blocks a PR**. ## Arguments @@ -175,7 +175,7 @@ When composed by `/review`: - **Input**: /review invokes `/assess-debt` during the completeness phase (Phase 4). - **Output**: Returns the debt assessment report. /review incorporates findings into review output (the Tech Debt section). - - Debt items are **informational** — they do **not** HALT the review and **never** block the PR (R7.2). + - Debt items are **informational** — they do **not** HALT the review and **never** block the PR. - /review does **not** auto-create tech-debt issues. Items worth tracking are promoted deliberately (after review) via `/write-issue` with the `tech-debt` label. When invoked **independently**: diff --git a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md index 694d9f97..c6bb8d3d 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md @@ -203,4 +203,4 @@ This skill supports `story`, `task`, `epic`, and `initiative` types. Adding a ne - No PM tool fallback: if the adopted tool fails, the skill HALTs — re-invocation is idempotent (`$id` prevents duplicate creation). - Template = source of truth for issue body format. Changes to template structure automatically affect all future issue creation. - Labels and hierarchy linking follow the PM tool implementation guide conventions. -- **Deliberate tech-debt promotion**: assess-* skills are output-only and never auto-create backlog items. When a debt or quality finding is worth scheduling, a human/agent promotes it here **deliberately** by passing `tech-debt` in `$labels` — a manual, selective act, never a 100% auto-conversion (R7.2). +- **Deliberate tech-debt promotion**: assess-* skills are output-only and never auto-create backlog items. When a debt or quality finding is worth scheduling, a human/agent promotes it here **deliberately** by passing `tech-debt` in `$labels` — a manual, selective act, never a 100% auto-conversion. diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index 3e59f5df..a063ad11 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -194,7 +194,7 @@ This phase uses a **4-level graceful degradation cascade** depending on which op 1. **Check**: Has `/assess-debt` already run in this session? 2. **Skip**: If already run — reuse results, move to Phase 5. 3. **Act**: Compose `/assess-debt` with `$scope = all`. `/assess-debt` is **output-only** — it returns a report and creates nothing. -4. **Act**: Report the debt items in the review output (Tech Debt section). Debt introduced by the PR is **surfaced, not blocked**: it does **not** HALT the review and **never** blocks the PR (R7.2). Do **not** auto-create a tech-debt issue. +4. **Act**: Report the debt items in the review output (Tech Debt section). Debt introduced by the PR is **surfaced, not blocked**: it does **not** HALT the review and **never** blocks the PR. Do **not** auto-create a tech-debt issue. 5. **Act**: If a debt item is worth scheduling, note it as a recommendation for **deliberate** promotion after review via `/write-issue` (with the `tech-debt` label) — a manual, selective act, never automatic. 6. **Verify**: Debt items recorded in the report. High-severity items may inform the review verdict (TECH-DEBT: approve + track separately) but never force CHANGES-REQUESTED on debt grounds alone. From e84304bdd161ddfc2c0d72c26b5ba6972dc02666 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 13 Jul 2026 19:58:37 +0200 Subject: [PATCH 8/8] [#313] fix: reword ADR-010 numbering note (no longer stale) Co-Authored-By: Claude Fable 5 --- .../tech/adr/adr-010-skill-authoring-effectiveness-standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md b/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md index 6dec512e..fde8093f 100644 --- a/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md +++ b/.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md @@ -4,7 +4,7 @@ **Date:** 2026-07-12 **Context:** Story #313 (Skill corpus effectiveness) — Task T2 -> Numbering note: `adr-009` exists on an unmerged branch at the time of writing; this ADR takes the next free number on the assumption that branch merges first. Renumber to 009 only if that branch is abandoned. +> Numbering note: `adr-010` is a valid, collision-free number — `adr-009` and `adr-011` through `adr-013` all exist on main. ## Decision