You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As Pair maintainers We want the 35-skill corpus optimized for LLM-executor effectiveness — trigger-oriented descriptions, cross-skill deduplication into shared references, progressive disclosure for the big orchestrators, sharpened completion criteria, router/catalog correctness fixes, and an updated authoring guideline with an eval procedure So that skills trigger reliably, cost less context, execute predictably (same process every run), and stay lean by discipline instead of periodic slimming passes
Parent Epic: None — standalone (the skills ARE the product; closest epic #209 is code quality, not skill quality) Status: Refined Priority: P1 (Should-Have)
Status Workflow
Refined: Story is detailed, estimated, and ready for development
In Progress: Story is actively being developed
Done: Story delivered and accepted
Background (audit evidence, 2026-07-12)
Three-source analysis: structural audit of the full corpus; official best practices (agentskills.io spec, Claude Code skill docs); the writing-great-skills reference model (predictability as root virtue; description = trigger; information hierarchy; completion criteria; no-op/sediment/duplication pruning; leading words; positive phrasing). Key findings:
Descriptions are capability summaries, not triggers (35/35); the 10 assess-* descriptions are near-clones; only next has when-to-use phrasing.
Cross-skill duplication: resolution cascade re-explained in 10 skills; idempotency prose restated in 28; graceful-degradation bullets near-verbatim in 34; way-of-working/PM-tool resolution re-derived in 18; /record-decision invocation contract restated in 19. Recurring scaffold ≈ 35–45% of a typical capability skill, 55–65% in assess-*.
Zero progressive disclosure: 35 monolithic SKILL.md, no auxiliary files; the 3 orchestrators (implement 423, review 391, bootstrap 314 lines) keep HALT conditions ~380 lines from the phases they govern.
Correctness bugs: next routes a 33-skill catalog but the corpus has 35 — checkpoint and grill are unreachable via the router; overlapping cascade rows (9/10) with the tie-break buried in Notes; markdown ordered-list numbering resets (review/refine-story/implement); load-bearing rules buried (verify-quality's only write disclosed at Notes L148; grill's HITL rule inside a step sub-bullet); forward references to non-existent skills (/brainstorm, /publish-pr) treated as live.
Worked examples: only grill has populated input→output transcripts; negations ("never X") used where positive phrasing steers better.
A meaning-preserving slimming pass (branch chore/skill-text-slimming) yielded only −1.8% — confirming the gains are structural and cross-file, not intra-file verbosity.
Acceptance Criteria
Functional Requirements
Given-When-Then Format:
Given the next router When it evaluates the catalog and cascades Then every installed skill is routable (catalog complete and derived from the actual corpus — checkpoint and grill included), no two cascade rows can co-fire ambiguously (distinguishing predicates in the rows, tie-break rule co-located with the table), and stated counts match reality.
Given the skill-authoring guideline (website contributing/writing-skills + KB skills-guide) When a maintainer writes or edits a skill Then the guideline documents the effectiveness standard — description=trigger, information hierarchy + progressive disclosure, completion criteria (checkable + exhaustive), pruning tests (no-op, sediment, duplication, single source of truth), leading words, positive phrasing, co-location — plus the agentskills.io constraints (name+description ≤1024 chars) and portability rules (no Claude-Code-only frontmatter in dataset skills). An ADR records the standard.
Given any of the 35 skill descriptions When an agent decides whether to load the skill Then the description states what the skill is and the trigger branches (one trigger per branch, no synonym duplication); mostly-composed capabilities carry a lean reach-clause description; the 10 assess-* descriptions are differentiated; body identity is not restated in the description.
Given a convention shared by many skills (resolution cascade, idempotency, graceful degradation, way-of-working/PM-tool resolution, /record-decision contract) When it needs to change Then it is edited in one shared KB reference (single source of truth) reached by context pointers from the skills; each skill keeps only its delta. Quantified: cascade explanation 10→1, idempotency prose 28→1 (+one-line per-skill delta), record-decision contract 19→1.
Given the 3 orchestrators (implement, review, bootstrap) When installed and executed Then their SKILL.md leads with steps and HALT/core rules; bulky in-file reference (edge-case inventories, degradation matrices, verbose examples) is disclosed into sibling files behind sharply-worded context pointers — and the install pipeline (pair-cli flatten+prefix) correctly ships multi-file skill dirs, or the CLI gap is fixed within this story.
Given the corpus after the pass When an executor runs any skill Then Verify beats are objectively checkable (and exhaustive where thoroughness matters), buried load-bearing rules are surfaced (verify-quality write-exception in its overview/Arguments; grill HITL rule as a Core Rule), forward references to non-existent skills are marked planned, negative rules are rephrased positively where possible, and skills with critical output contracts (write-issue, record-decision, checkpoint) carry one populated input→output example.
Given the rewritten descriptions When the change is evaluated Then there is before/after trigger-test evidence: a should-trigger / should-not-trigger prompt set per skill family, run against old vs new descriptions, with results recorded; the eval procedure is documented in the guideline.
Given the full change set When CI runs Then all gates are green (knowledge-hub tests, links, mdlint, docs-staleness — including the skills-catalog rows affected by description changes) and dataset + installed mirrors are byte-consistent under the mirror transform in every commit.
Business Rules
Predictability over brevity: cuts and moves serve same-process-every-run, never token count per se.
Single source of truth for every shared convention; skills carry deltas only (same principle as adoption files).
Portability: dataset skills use only agentskills.io-core frontmatter; assistant-specific fields are out.
Mirror-sync discipline: dataset + .claude/skills mirror in the same commit, always.
Edge Cases and Error Handling
Multi-file skill install unsupported (T5): if pair-cli flatten+prefix can't ship sibling files, extend the CLI in-story (registry + link rewriting already handle cross-references per Skill install: flatten + prefix + cross-reference rewriting from nested dataset #238); only if that proves disproportionate, deliver orchestrators as improved single-file (hierarchy reordered, reference co-located at bottom) and record the CLI gap as an explicit follow-up in this story's ledger — not silently.
Description limits: enforce name+description ≤1024 chars in the conformance check.
Trigger regressions (T3): if the eval shows a rewritten description triggering worse, revert that skill's description and iterate — eval gates the rewrite.
Shared-reference loading: a pointer that fires unreliably on must-have material gets its wording sharpened first; inline only if sharpening fails.
Definition of Done Checklist
Development Completion
All acceptance criteria implemented and verified
Delivered on a single PR per story (tasks are commits/checkboxes within it)
ADR recorded (skill-authoring effectiveness standard)
Guideline + skills-guide updated; docs-staleness green
Dataset + mirror byte-consistent in every commit
Code review completed and approved
Quality Assurance
Conformance: no assistant-specific frontmatter in dataset skills; description limits respected
Trigger eval evidence attached (before/after)
next routes every skill in a dry-run
Story Sizing and Sprint Readiness
Refined Story Points
Final Story Points: 8 (XL) — umbrella, delivered across multiple small PRs Confidence Level: Medium Sizing Justification: broad surface (35 skills ×2 copies + guidelines + docs + possible CLI work) but each task is mechanical once the standard (T2) exists; audit already done, no discovery left.
Sprint Capacity Validation
Sprint Fit Assessment: does NOT fit one sprint as a whole — worked task-by-task (T1 and T2 are each half-day starters).
Story Splitting Recommendations
Tasks are the natural split; T1 (correctness fixes) is shippable immediately and valuable standalone.
Testing Methods: trigger eval (should/should-not prompt sets, before/after); next routing dry-run over the full catalog; static conformance (frontmatter portability, description limits, pointer resolution); standard gates. Test Data Requirements: prompt sets per skill family (created in T7).
Notes and Additional Context
Refinement Session Insights: the corpus is exemplary on internal conformance (uniform scaffold, C/S/A/V, HALT, composition contracts) — the gap is effectiveness, which the internal guideline never covered. Reference model: mattpocock/skillswriting-great-skills (+GLOSSARY) — predictability as root virtue; agentskills.io spec; Claude Code skill docs (progressive-disclosure lifecycle, eval practice). Documentation Links: audit + best-practice synthesis in session working docs; slimming review on branch chore/skill-text-slimming.
Technical Analysis
Implementation Approach
Technical Strategy: fix correctness first (T1), codify the standard (T2 + ADR), then apply it in three mechanical passes (descriptions T3, dedup T4, disclosure T5, steering T6) gated by an eval (T7). Every pass = dataset + mirror in the same commit. Key Components: dataset/.skills/**/SKILL.md (35 + new shared reference files), .claude/skills/** mirrors, .pair/knowledge/skills-guide.md, KB shared-conventions reference (new), apps/website/content/docs/contributing/writing-skills.mdx, apps/pair-cli (T5 if needed), docs-staleness script (catalog rows). Integration Points: pair-cli install (flatten + prefix + cross-reference rewriting, #238); docs-staleness gate; skills-catalog.mdx.
Technical Risks and Mitigation
Risk
Impact
Probability
Mitigation
Rewritten descriptions trigger worse
High
Medium
T7 eval gates T3; per-skill revert path
Shared-reference pointers not followed by executors
Medium
Medium
Sharpen pointer wording; inline fallback per edge case rule
Multi-file skills break install/mirror pipeline
Medium
Medium
T5 prereq check on pair-cli; CLI extension in-story; explicit fallback
T1 ─────────────────────────┐
T2 ─► T3 ─► T7 (eval gates T3)│
T2 ─► T4 ─────────────────────┼─► done
T2 ─► T5 ─────────────────────┤
T2 ─► T6 ─────────────────────┘
(T1 independent, do first; T3..T6 parallelizable after T2 if file-disjoint batches)
AC Coverage
Task
AC1
AC2
AC3
AC4
AC5
AC6
AC7
AC8
T1
✓
✓
T2
✓
✓
T2b
T3
✓
✓
T4
✓
✓
T5
✓
✓
T6
✓
✓
T7
✓
✓
✓
T8
✓
✓
Detailed Tasks
T1 — Router/catalog + correctness fixes
Task Information — Priority: P1 · Est: 0.5d · Bounded Context: Adoption & Guidelines (skills) Type: Bug Fix Description: Fix next's catalog (33→actual corpus; add checkpoint + grill to catalog and suggestion cascades; correct stated counts; make the catalog derivation explicit so it can't drift again); disambiguate overlapping cascade rows (distinguishing predicate in-row, tie-break co-located with the table); fix markdown ordered-list numbering resets (review Step 6.2, refine-story Step 1, implement Phase 3); surface buried load-bearing rules (verify-quality's Step 5.C write-exception into overview + Arguments; grill's never-answer-for-the-human as a Core Rule); mark /brainstorm and /publish-pr forward references as planned with issue links. Acceptance Criteria: AC1; next dry-run routes checkpoint and grill; numbering renders sequentially; each surfaced rule visible in the skill's top section. Files to Modify:dataset/.skills/next/SKILL.md, capability/{verify-quality,grill,checkpoint}/SKILL.md, process/{review,refine-story,implement}/SKILL.md (+ mirrors). Dependencies: none — do first. Testing: next routing dry-run; mdlint; visual render check of renumbered lists.
T2 — Authoring effectiveness standard
Task Information — Priority: P1 · Est: 1d · Bounded Context: Adoption & Guidelines Type: Documentation Description: Rewrite the skill-authoring guidance to cover effectiveness, not just conformance: description=trigger (branches, one trigger each, reach clauses for composed capabilities); information hierarchy (steps > in-file reference > disclosed reference) + progressive disclosure mechanics; completion criteria (checkable + exhaustive); pruning discipline (no-op test, sediment, duplication vs single source of truth, relevance); leading words; positive phrasing over negation; co-location; agentskills.io limits; portability (core frontmatter only). Update both the website page and the KB skills-guide.md. Record the ADR. Acceptance Criteria: AC2; guideline usable as review checklist for T3–T6. Files to Modify:apps/website/content/docs/contributing/writing-skills.mdx, dataset/.pair/knowledge/skills-guide.md (+ root mirror), new ADR in .pair/adoption/tech/adr/. Dependencies: none (parallel to T1). Testing: docs-staleness; review checklist applied to one existing skill as smoke test.
T2b — Extend meaning-preserving slimming to the 14 previously mutex-excluded skills
Task Information — Priority: P2 · Est: 0.5d · Bounded Context: Adoption & Guidelines (skills) Type: Refactoring Description: A standalone chore (chore/skill-text-slimming, merged 2026-07-13) ran a meaning-preserving text-compression pass over 16 of 35 skills, explicitly excluding 14 (all 10 assess-*, record-decision, write-issue, bootstrap, review) because they were mutexed with the then-open PR #310 (story #224). #310 has since merged, lifting the mutex. This task completes corpus coverage: apply the identical pass (hunk-verified redundant-only cuts, no meaning loss, dataset+mirror in sync) to the remaining 14. Net effect on the earlier pass was modest (~1.5% words) — this task is expected to be similarly modest, not a rewrite; it is a mechanical completion of the earlier pass, distinct from T3-T6's structural rewrites (which will likely touch these same files again, more substantially). Acceptance Criteria: all 14 skills reviewed hunk-by-hunk against origin/main; every cut verified redundant elsewhere in the same file; dataset+mirror byte-consistent under the transform for all 14; corpus-wide grep for the "no project ADR/log/code citation" rule (see checkpoint/SKILL.md fix, PR #319) re-confirmed clean. Files to Modify:capability/assess-{ai,architecture,code-quality,debt,infrastructure,methodology,observability,pm,stack,testing}/SKILL.md, capability/record-decision/SKILL.md, capability/write-issue/SKILL.md, process/bootstrap/SKILL.md, process/review/SKILL.md (dataset + mirrors, 28 files). Dependencies:#310 merged (done — mutex lifted); independent of T3-T7. Testing: same as the original slimming pass — knowledge-hub tests, check:links, mdlint, docs-staleness; independent review verifying no meaning lost, hunk-by-hunk.
T3 — Descriptions → trigger-oriented
Task Information — Priority: P1 · Est: 1d · Bounded Context: Adoption & Guidelines (skills) Type: Refactoring Description: Rewrite all 35 frontmatter descriptions per the T2 standard: what + trigger branches; deduplicate the 10 assess-* clones; lean reach-clause descriptions for mostly-composed capabilities (checkpoint, estimate, write-issue, grill, map-*, record-decision…); remove body identity from descriptions; enforce ≤1024 chars. Sync skills-catalog.mdx rows (staleness gate). Acceptance Criteria: AC3; T7 eval shows no trigger regression, improvement on weak skills. Files to Modify: all 35 SKILL.md frontmatter (+ mirrors), apps/website/content/docs/reference/skills-catalog.mdx. Dependencies: T2 (standard), T7 harness for the gate; after #310 merge + slimming fold. Testing: T7 before/after eval; docs-staleness.
T4 — Cross-skill dedup → shared KB references
Task Information — Priority: P1 · Est: 1.5d · Bounded Context: Adoption & Guidelines Type: Refactoring Description: Extract the five shared conventions into single-source KB reference file(s) (external reference, e.g. dataset/.pair/knowledge/skill-conventions/…): resolution cascade (10 skills), idempotency convention (28), graceful-degradation standard bullets (34), way-of-working/PM-tool resolution (18), /record-decision invocation contract (19). Replace inline restatements with sharply-worded context pointers + per-skill deltas only. Acceptance Criteria: AC4 with the quantified targets; no skill loses a behavior (each replaced block's unique content either moves to the shared file or stays as delta). Files to Modify: new shared reference files; the affected skills (+ mirrors). Dependencies: T2; after #310 merge. Testing: knowledge-hub tests; links; spot dry-runs of 3 skills relying on pointed-to conventions.
Addendum (2026-07-13, confirmed by inspection post-#310): a sixth dedup target — Output Format. The 8 "decision" assess-* skills (ai, architecture, infrastructure, methodology, observability, pm, stack, testing) already share, de facto, an identical ASCII output shape (Domain/Path/Decision/Proposal/Target/Persist/Status) — only the field values differ, not the structure. The 2 "report" assess-* skills (code-quality, debt) share a second, distinct shape (metrics → items/hotspots → recommendations → RESULT). T4 should formalize BOTH as named shared shapes in the new shared-reference file, not just prose rules — so a new assess-* skill inherits the right shape by reference instead of re-deriving it. No new skill work needed to converge them (they already match); this is a documentation/contract step.
T5 — Progressive disclosure for the orchestrators
Task Information — Priority: P2 · Est: 1.5d · Bounded Context: Adoption & Guidelines + Collaborative Workflow (CLI) Type: Refactoring Description: For implement (423), review (391), bootstrap (314): keep steps + HALT + core rules on top of SKILL.md; disclose bulky reference (edge-case inventories, degradation matrices Level 1–4, verbose examples, section-ownership tables) into named sibling files behind context pointers. PREREQ: verify pair-cli install/mirror ships multi-file skill dirs with link rewriting (#238 machinery); extend the CLI if not; explicit fallback per Edge Cases. Acceptance Criteria: AC5; installed mirror resolves all pointers; orchestrator dry-run reaches disclosed material when needed. Files to Modify:process/{implement,review,bootstrap}/ (SKILL.md + new sibling .md files, + mirrors); possibly apps/pair-cli/src/registry/*. Dependencies: T2. Testing: install dry-run (fixture) with multi-file skill; e2e if CLI touched.
T6 — Completion criteria + steering pass
Task Information — Priority: P2 · Est: 1d · Bounded Context: Adoption & Guidelines (skills) Type: Refactoring Description: Corpus pass applying T2's steering rules: sharpen soft Verify beats into checkable/exhaustive conditions (bootstrap "internally consistent", assess-* "guidelines loaded", refine-story approval gates → explicit observable conditions or honest HITL gates); convert negations to positive phrasing where a positive target exists; add one populated input→output example to write-issue, record-decision, checkpoint; co-locate scattered rule fragments (e.g. review's Level table + prose blocks). Acceptance Criteria: AC6; sampled skills pass the T2 review checklist. Files to Modify: affected skills (+ mirrors). Dependencies: T2; after #310 merge. Testing: T2 checklist review on the full diff; gates.
T7 — Trigger/effectiveness eval + conformance
Task Information — Priority: P1 · Est: 1d · Bounded Context: Integration & Process Standardization Type: Testing Description: Build the eval: should-trigger / should-not-trigger prompt sets per skill family; run against old vs new descriptions (fresh sessions), record results; add a static conformance check (description ≤1024 chars, core-frontmatter-only, pointer targets resolve, catalog counts derived). Document the procedure in the guideline. The eval GATES T3 (see Dependency Graph). Acceptance Criteria: AC7 + conformance in AC8; results committed as evidence. Files to Modify: eval prompt sets + runner notes (location per T2 decision, e.g. packages/knowledge-hub/eval/ or docs), conformance script wired into quality gate. Dependencies: T2 (procedure), pairs with T3. Testing: eval run itself; conformance in CI.
Story Statement
As Pair maintainers
We want the 35-skill corpus optimized for LLM-executor effectiveness — trigger-oriented descriptions, cross-skill deduplication into shared references, progressive disclosure for the big orchestrators, sharpened completion criteria, router/catalog correctness fixes, and an updated authoring guideline with an eval procedure
So that skills trigger reliably, cost less context, execute predictably (same process every run), and stay lean by discipline instead of periodic slimming passes
Where:
packages/knowledge-hub/dataset/.skills/**+ installed mirrors (.claude/skills/**), KB guidelines (.pair/knowledge/), website contributing docs, possiblyapps/pair-cli(multi-file skill install)Epic Context
Parent Epic: None — standalone (the skills ARE the product; closest epic #209 is code quality, not skill quality)
Status: Refined
Priority: P1 (Should-Have)
Status Workflow
Background (audit evidence, 2026-07-12)
Three-source analysis: structural audit of the full corpus; official best practices (agentskills.io spec, Claude Code skill docs); the
writing-great-skillsreference model (predictability as root virtue; description = trigger; information hierarchy; completion criteria; no-op/sediment/duplication pruning; leading words; positive phrasing). Key findings:assess-*descriptions are near-clones; onlynexthas when-to-use phrasing./record-decisioninvocation contract restated in 19. Recurring scaffold ≈ 35–45% of a typical capability skill, 55–65% inassess-*.nextroutes a 33-skill catalog but the corpus has 35 — checkpoint and grill are unreachable via the router; overlapping cascade rows (9/10) with the tie-break buried in Notes; markdown ordered-list numbering resets (review/refine-story/implement); load-bearing rules buried (verify-quality's only write disclosed at Notes L148; grill's HITL rule inside a step sub-bullet); forward references to non-existent skills (/brainstorm,/publish-pr) treated as live.A meaning-preserving slimming pass (branch
chore/skill-text-slimming) yielded only −1.8% — confirming the gains are structural and cross-file, not intra-file verbosity.Acceptance Criteria
Functional Requirements
Given-When-Then Format:
Given the
nextrouterWhen it evaluates the catalog and cascades
Then every installed skill is routable (catalog complete and derived from the actual corpus — checkpoint and grill included), no two cascade rows can co-fire ambiguously (distinguishing predicates in the rows, tie-break rule co-located with the table), and stated counts match reality.
Given the skill-authoring guideline (website
contributing/writing-skills+ KBskills-guide)When a maintainer writes or edits a skill
Then the guideline documents the effectiveness standard — description=trigger, information hierarchy + progressive disclosure, completion criteria (checkable + exhaustive), pruning tests (no-op, sediment, duplication, single source of truth), leading words, positive phrasing, co-location — plus the agentskills.io constraints (name+description ≤1024 chars) and portability rules (no Claude-Code-only frontmatter in dataset skills). An ADR records the standard.
Given any of the 35 skill descriptions
When an agent decides whether to load the skill
Then the description states what the skill is and the trigger branches (one trigger per branch, no synonym duplication); mostly-composed capabilities carry a lean reach-clause description; the 10
assess-*descriptions are differentiated; body identity is not restated in the description.Given a convention shared by many skills (resolution cascade, idempotency, graceful degradation, way-of-working/PM-tool resolution,
/record-decisioncontract)When it needs to change
Then it is edited in one shared KB reference (single source of truth) reached by context pointers from the skills; each skill keeps only its delta. Quantified: cascade explanation 10→1, idempotency prose 28→1 (+one-line per-skill delta), record-decision contract 19→1.
Given the 3 orchestrators (implement, review, bootstrap)
When installed and executed
Then their SKILL.md leads with steps and HALT/core rules; bulky in-file reference (edge-case inventories, degradation matrices, verbose examples) is disclosed into sibling files behind sharply-worded context pointers — and the install pipeline (pair-cli flatten+prefix) correctly ships multi-file skill dirs, or the CLI gap is fixed within this story.
Given the corpus after the pass
When an executor runs any skill
Then Verify beats are objectively checkable (and exhaustive where thoroughness matters), buried load-bearing rules are surfaced (verify-quality write-exception in its overview/Arguments; grill HITL rule as a Core Rule), forward references to non-existent skills are marked planned, negative rules are rephrased positively where possible, and skills with critical output contracts (write-issue, record-decision, checkpoint) carry one populated input→output example.
Given the rewritten descriptions
When the change is evaluated
Then there is before/after trigger-test evidence: a should-trigger / should-not-trigger prompt set per skill family, run against old vs new descriptions, with results recorded; the eval procedure is documented in the guideline.
Given the full change set
When CI runs
Then all gates are green (knowledge-hub tests, links, mdlint, docs-staleness — including the skills-catalog rows affected by description changes) and dataset + installed mirrors are byte-consistent under the mirror transform in every commit.
Business Rules
chore/skill-text-slimming) is complementary content-pruning: merge or fold before T3 touches the same files..claude/skillsmirror in the same commit, always.Edge Cases and Error Handling
Definition of Done Checklist
Development Completion
Quality Assurance
nextroutes every skill in a dry-runStory Sizing and Sprint Readiness
Refined Story Points
Final Story Points: 8 (XL) — umbrella, delivered across multiple small PRs
Confidence Level: Medium
Sizing Justification: broad surface (35 skills ×2 copies + guidelines + docs + possible CLI work) but each task is mechanical once the standard (T2) exists; audit already done, no discovery left.
Sprint Capacity Validation
Sprint Fit Assessment: does NOT fit one sprint as a whole — worked task-by-task (T1 and T2 are each half-day starters).
Story Splitting Recommendations
Tasks are the natural split; T1 (correctness fixes) is shippable immediately and valuable standalone.
Dependencies and Coordination
Story Dependencies
Prerequisite Stories: #224/PR #310 merged (14 overlapping skills). Slimming branch
chore/skill-text-slimmingmerged or folded before T3.Dependent Stories: none.
Shared Components: entire skill corpus;
skills-guide.md;writing-skillsdocs page; docs-staleness gate; pair-cli install pipeline (T5).Validation and Testing Strategy
Acceptance Testing Approach
Testing Methods: trigger eval (should/should-not prompt sets, before/after);
nextrouting dry-run over the full catalog; static conformance (frontmatter portability, description limits, pointer resolution); standard gates.Test Data Requirements: prompt sets per skill family (created in T7).
Notes and Additional Context
Refinement Session Insights: the corpus is exemplary on internal conformance (uniform scaffold, C/S/A/V, HALT, composition contracts) — the gap is effectiveness, which the internal guideline never covered. Reference model:
mattpocock/skillswriting-great-skills(+GLOSSARY) — predictability as root virtue; agentskills.io spec; Claude Code skill docs (progressive-disclosure lifecycle, eval practice).Documentation Links: audit + best-practice synthesis in session working docs; slimming review on branch
chore/skill-text-slimming.Technical Analysis
Implementation Approach
Technical Strategy: fix correctness first (T1), codify the standard (T2 + ADR), then apply it in three mechanical passes (descriptions T3, dedup T4, disclosure T5, steering T6) gated by an eval (T7). Every pass = dataset + mirror in the same commit.
Key Components:
dataset/.skills/**/SKILL.md(35 + new shared reference files),.claude/skills/**mirrors,.pair/knowledge/skills-guide.md, KB shared-conventions reference (new),apps/website/content/docs/contributing/writing-skills.mdx,apps/pair-cli(T5 if needed), docs-staleness script (catalog rows).Integration Points: pair-cli install (flatten + prefix + cross-reference rewriting, #238); docs-staleness gate; skills-catalog.mdx.
Technical Risks and Mitigation
Task Breakdown
Checklist
Dependency Graph
AC Coverage
Detailed Tasks
T1 — Router/catalog + correctness fixes
Task Information — Priority: P1 · Est: 0.5d · Bounded Context: Adoption & Guidelines (skills)
Type: Bug Fix
Description: Fix
next's catalog (33→actual corpus; add checkpoint + grill to catalog and suggestion cascades; correct stated counts; make the catalog derivation explicit so it can't drift again); disambiguate overlapping cascade rows (distinguishing predicate in-row, tie-break co-located with the table); fix markdown ordered-list numbering resets (review Step 6.2, refine-story Step 1, implement Phase 3); surface buried load-bearing rules (verify-quality's Step 5.C write-exception into overview + Arguments; grill's never-answer-for-the-human as a Core Rule); mark/brainstormand/publish-prforward references as planned with issue links.Acceptance Criteria: AC1;
nextdry-run routes checkpoint and grill; numbering renders sequentially; each surfaced rule visible in the skill's top section.Files to Modify:
dataset/.skills/next/SKILL.md,capability/{verify-quality,grill,checkpoint}/SKILL.md,process/{review,refine-story,implement}/SKILL.md(+ mirrors).Dependencies: none — do first.
Testing: next routing dry-run; mdlint; visual render check of renumbered lists.
T2 — Authoring effectiveness standard
Task Information — Priority: P1 · Est: 1d · Bounded Context: Adoption & Guidelines
Type: Documentation
Description: Rewrite the skill-authoring guidance to cover effectiveness, not just conformance: description=trigger (branches, one trigger each, reach clauses for composed capabilities); information hierarchy (steps > in-file reference > disclosed reference) + progressive disclosure mechanics; completion criteria (checkable + exhaustive); pruning discipline (no-op test, sediment, duplication vs single source of truth, relevance); leading words; positive phrasing over negation; co-location; agentskills.io limits; portability (core frontmatter only). Update both the website page and the KB
skills-guide.md. Record the ADR.Acceptance Criteria: AC2; guideline usable as review checklist for T3–T6.
Files to Modify:
apps/website/content/docs/contributing/writing-skills.mdx,dataset/.pair/knowledge/skills-guide.md(+ root mirror), new ADR in.pair/adoption/tech/adr/.Dependencies: none (parallel to T1).
Testing: docs-staleness; review checklist applied to one existing skill as smoke test.
T2b — Extend meaning-preserving slimming to the 14 previously mutex-excluded skills
Task Information — Priority: P2 · Est: 0.5d · Bounded Context: Adoption & Guidelines (skills)
Type: Refactoring
Description: A standalone chore (
chore/skill-text-slimming, merged 2026-07-13) ran a meaning-preserving text-compression pass over 16 of 35 skills, explicitly excluding 14 (all 10assess-*,record-decision,write-issue,bootstrap,review) because they were mutexed with the then-open PR #310 (story #224). #310 has since merged, lifting the mutex. This task completes corpus coverage: apply the identical pass (hunk-verified redundant-only cuts, no meaning loss, dataset+mirror in sync) to the remaining 14. Net effect on the earlier pass was modest (~1.5% words) — this task is expected to be similarly modest, not a rewrite; it is a mechanical completion of the earlier pass, distinct from T3-T6's structural rewrites (which will likely touch these same files again, more substantially).Acceptance Criteria: all 14 skills reviewed hunk-by-hunk against
origin/main; every cut verified redundant elsewhere in the same file; dataset+mirror byte-consistent under the transform for all 14; corpus-wide grep for the "no project ADR/log/code citation" rule (see checkpoint/SKILL.md fix, PR #319) re-confirmed clean.Files to Modify:
capability/assess-{ai,architecture,code-quality,debt,infrastructure,methodology,observability,pm,stack,testing}/SKILL.md,capability/record-decision/SKILL.md,capability/write-issue/SKILL.md,process/bootstrap/SKILL.md,process/review/SKILL.md(dataset + mirrors, 28 files).Dependencies: #310 merged (done — mutex lifted); independent of T3-T7.
Testing: same as the original slimming pass — knowledge-hub tests, check:links, mdlint, docs-staleness; independent review verifying no meaning lost, hunk-by-hunk.
T3 — Descriptions → trigger-oriented
Task Information — Priority: P1 · Est: 1d · Bounded Context: Adoption & Guidelines (skills)
Type: Refactoring
Description: Rewrite all 35 frontmatter descriptions per the T2 standard: what + trigger branches; deduplicate the 10 assess-* clones; lean reach-clause descriptions for mostly-composed capabilities (checkpoint, estimate, write-issue, grill, map-*, record-decision…); remove body identity from descriptions; enforce ≤1024 chars. Sync skills-catalog.mdx rows (staleness gate).
Acceptance Criteria: AC3; T7 eval shows no trigger regression, improvement on weak skills.
Files to Modify: all 35
SKILL.mdfrontmatter (+ mirrors),apps/website/content/docs/reference/skills-catalog.mdx.Dependencies: T2 (standard), T7 harness for the gate; after #310 merge + slimming fold.
Testing: T7 before/after eval; docs-staleness.
T4 — Cross-skill dedup → shared KB references
Task Information — Priority: P1 · Est: 1.5d · Bounded Context: Adoption & Guidelines
Type: Refactoring
Description: Extract the five shared conventions into single-source KB reference file(s) (external reference, e.g.
dataset/.pair/knowledge/skill-conventions/…): resolution cascade (10 skills), idempotency convention (28), graceful-degradation standard bullets (34), way-of-working/PM-tool resolution (18),/record-decisioninvocation contract (19). Replace inline restatements with sharply-worded context pointers + per-skill deltas only.Acceptance Criteria: AC4 with the quantified targets; no skill loses a behavior (each replaced block's unique content either moves to the shared file or stays as delta).
Files to Modify: new shared reference files; the affected skills (+ mirrors).
Dependencies: T2; after #310 merge.
Testing: knowledge-hub tests; links; spot dry-runs of 3 skills relying on pointed-to conventions.
Addendum (2026-07-13, confirmed by inspection post-#310): a sixth dedup target — Output Format. The 8 "decision" assess-* skills (ai, architecture, infrastructure, methodology, observability, pm, stack, testing) already share, de facto, an identical ASCII output shape (
Domain/Path/Decision/Proposal/Target/Persist/Status) — only the field values differ, not the structure. The 2 "report" assess-* skills (code-quality, debt) share a second, distinct shape (metrics → items/hotspots → recommendations → RESULT). T4 should formalize BOTH as named shared shapes in the new shared-reference file, not just prose rules — so a new assess-* skill inherits the right shape by reference instead of re-deriving it. No new skill work needed to converge them (they already match); this is a documentation/contract step.T5 — Progressive disclosure for the orchestrators
Task Information — Priority: P2 · Est: 1.5d · Bounded Context: Adoption & Guidelines + Collaborative Workflow (CLI)
Type: Refactoring
Description: For implement (423), review (391), bootstrap (314): keep steps + HALT + core rules on top of SKILL.md; disclose bulky reference (edge-case inventories, degradation matrices Level 1–4, verbose examples, section-ownership tables) into named sibling files behind context pointers. PREREQ: verify pair-cli install/mirror ships multi-file skill dirs with link rewriting (#238 machinery); extend the CLI if not; explicit fallback per Edge Cases.
Acceptance Criteria: AC5; installed mirror resolves all pointers; orchestrator dry-run reaches disclosed material when needed.
Files to Modify:
process/{implement,review,bootstrap}/(SKILL.md + new sibling .md files, + mirrors); possiblyapps/pair-cli/src/registry/*.Dependencies: T2.
Testing: install dry-run (fixture) with multi-file skill; e2e if CLI touched.
T6 — Completion criteria + steering pass
Task Information — Priority: P2 · Est: 1d · Bounded Context: Adoption & Guidelines (skills)
Type: Refactoring
Description: Corpus pass applying T2's steering rules: sharpen soft Verify beats into checkable/exhaustive conditions (bootstrap "internally consistent", assess-* "guidelines loaded", refine-story approval gates → explicit observable conditions or honest HITL gates); convert negations to positive phrasing where a positive target exists; add one populated input→output example to write-issue, record-decision, checkpoint; co-locate scattered rule fragments (e.g. review's Level table + prose blocks).
Acceptance Criteria: AC6; sampled skills pass the T2 review checklist.
Files to Modify: affected skills (+ mirrors).
Dependencies: T2; after #310 merge.
Testing: T2 checklist review on the full diff; gates.
T7 — Trigger/effectiveness eval + conformance
Task Information — Priority: P1 · Est: 1d · Bounded Context: Integration & Process Standardization
Type: Testing
Description: Build the eval: should-trigger / should-not-trigger prompt sets per skill family; run against old vs new descriptions (fresh sessions), record results; add a static conformance check (description ≤1024 chars, core-frontmatter-only, pointer targets resolve, catalog counts derived). Document the procedure in the guideline. The eval GATES T3 (see Dependency Graph).
Acceptance Criteria: AC7 + conformance in AC8; results committed as evidence.
Files to Modify: eval prompt sets + runner notes (location per T2 decision, e.g.
packages/knowledge-hub/eval/or docs), conformance script wired into quality gate.Dependencies: T2 (procedure), pairs with T3.
Testing: eval run itself; conformance in CI.
T8 — Skill naming taxonomy (analyze-* rename + category coherence)
Task Information — Priority: P1 · Est: 0.5d · Bounded Context: Adoption & Guidelines (skills)
Type: Refactoring
Description: Disambiguate the three skill verbs that
assess-*currently conflates. Adopt a strict tripartition:verify-*= conformance pass/fail (unchanged);assess-*= evaluate options + PROPOSE an adoption choice (the 8 decision skills, unchanged); NEWanalyze-*= analyze + REPORT only, never blocks, no decision. Rename the 2 report skills accordingly —assess-debt→analyze-debt,assess-code-quality→analyze-code-quality— across dataset dir +.claudemirror (git mvto preserve history; frontmattername, H1 title, self-refs updated). Update every cross-reference:nextrouter catalog + suggestion cascade (category "Analysis"),/reviewrequired composition contract,skills-guide.mdcategories (Verification = only the 3verify-*; new "Analysis" group;manage-flags→ Operational; dissolve the "Code Quality" bucket) + a Migration Notes entry (dataset + root mirror),skills-catalog.mdx(new "Analysis Capabilities" section),concepts/skills.mdx,writing-skills.mdxverb taxonomy, the eval trigger-prompts + the #224 conformance test. Record the taxonomy decision as an ADL.Acceptance Criteria: AC2 (guideline documents the verb tripartition), AC8 (docs-staleness / skills-conformance / knowledge-hub mirror tests / check:links / mdlint green; dataset + mirror byte-consistent under the transform); skill COUNT stays 35 (rename, not add/remove); zero residual live
assess-debt/assess-code-qualityrefs (point-in-time historical records — ADR-009, the 2026-07-12 eval baseline, Migration Notes — excepted).Files to Modify:
capability/{analyze-debt,analyze-code-quality}/SKILL.md(renamed, + mirrors),next/SKILL.md,process/review/SKILL.md(+ mirrors),dataset/.pair/knowledge/skills-guide.md(+ root mirror),apps/website/content/docs/reference/skills-catalog.mdx,apps/website/content/docs/concepts/skills.mdx,apps/website/content/docs/contributing/writing-skills.mdx,packages/knowledge-hub/eval/trigger-prompts.json,packages/knowledge-hub/src/conformance/assess-output-only.test.ts, new ADL.pair/adoption/decision-log/2026-07-13-skill-naming-verb-taxonomy.md.Dependencies: #310 merged; conceptually after T1 (router/catalog). Folded into #313's single PR.
Testing:
pnpm docs:staleness,pnpm skills:conformance,pnpm --filter @pair/knowledge-hub test(+ check:links),pnpm mdlint:check; whole-repo residual grep for old names.