[#313] docs: skill authoring effectiveness standard (task T2)

[rucka]

Skill authoring effectiveness standard (#313, task T2)

Story: Part of #313 (task T2 of T1-T7) — standalone reviewable slice
Type: Documentation · Priority: P1 · Risk: Low (docs + 1 ADR, no skill content changed)

Motivation

An audit of the 35-skill corpus (best practices from agentskills.io + Claude Code skill docs + the mattpocock/skills reference model) found the corpus is exemplary on internal conformance (uniform scaffold, Check/Skip/Act/Verify, HALT, composition contracts) but the internal guideline never covered effectiveness: trigger-oriented descriptions, information hierarchy/progressive disclosure, checkable completion criteria, pruning discipline, leading words, positive phrasing. This task lands the standard itself; T3-T6 (later, sequenced after PR #310 merges) apply it to the corpus.

Changes Made

• Extended apps/website/content/docs/contributing/writing-skills.mdx: mechanics (types/structure/anatomy/composition) kept verbatim; new "The effectiveness standard" section with 9 numbered principles (description=trigger, information hierarchy + progressive disclosure, completion criteria, pruning discipline, leading words, positive phrasing, co-location, constraints, evaluation), each with a decidable "how to check" test, plus a review checklist usable as the T3-T6 gate.
• Condensed the same 9 points into .pair/knowledge/skills-guide.md (dataset + root mirror).
• New ADR adr-010-skill-authoring-effectiveness-standard.md recording the decision/rationale/consequences.
• Remediation round 1: fixed principle 8 (misstated the agentskills.io spec — version/author aren't top-level spec fields, only example metadata: keys; now explicitly whitelisted as a tolerated Pair extension); fixed the size-limit attribution (spec caps name/description separately, Pair's combined bound is stricter); made the leading-words check decidable; softened an overclaim ("worked examples" → "illustrative examples"); rewrote 5 passages that were verbatim/near-verbatim lifts from the CC-licensed reference model.
• Remediation rounds 2-4: a fresh re-scan after round 1 found further verbatim/near-verbatim text the first pass missed, including 2 exact phrase matches ("inline the material only if sharpening fails", "each meaning lives in exactly one authoritative place"). Round 4 switched method — a mechanical n-gram scan (4+ consecutive identical words) against both source files, converged from 39 matches to 0 across 4 edit→rescan iterations, independently reproduced by the reviewer (not trusted on the author's count).

Files Changed

• apps/website/content/docs/contributing/writing-skills.mdx
• packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md + root mirror .pair/knowledge/skills-guide.md
• .pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md (new)

Testing / Quality Gates

mdlint:            0 errors (incl. the round-4 MD034 bare-URL fix)
docs:staleness:     PASS — 35 skills, 8 commands in sync
check:links:        all valid
knowledge-hub test: 56/56 pass

Risk Assessment

Low — pure documentation/guideline addition, zero skill files touched (mutex with PR #310's 14 skills fully respected).

Reviewer notes (disclosures)

• Scope discipline: only these 3 files touched across all 4 commits — no SKILL.md, no skills-catalog.
• License-risk finding taken seriously: 3 full review rounds specifically hunting for text too close to the CC-licensed mattpocock/skills reference — round 4's mechanical scan is a genuine methodology upgrade over rounds 1-3's eyeball-only approach, and the reviewer independently reproduced the "0 matches" claim with their own script rather than trusting it.
• Meaning preserved throughout: all 9 principles verified, after every round, to still assert the identical rule — this was a wording-only pass.

🤖 Generated with Claude Code

[rucka]

Code Review — PR #319 (Independent, consolidated)

Review Information

• PR: [#313] docs: skill authoring effectiveness standard (task T2) #319 — [#313] docs: skill authoring effectiveness standard (task T2)
• Reviewer: Independent reviewer (Claude Code)
• Story: Skill corpus effectiveness: trigger descriptions, shared references, progressive disclosure, sharpened criteria, router fixes, authoring standard + eval #313 (task T2)
• Review Type: Documentation
• Head reviewed: 9693188

Review Summary

Overall Assessment

• Approved

4 review rounds on this PR, driven by a genuine license-risk concern: the standard is conceptually grounded in the mattpocock/skills reference model, and rounds 1-3 kept finding residual verbatim/near-verbatim text after each fix (the trap: reordering the same words or swapping "agent"→"executor" is not a rewrite). Round 4 switched to a mechanical n-gram scan (4+ consecutive identical words) against both source files — converged 39→0 matches. I independently reproduced this scan myself (own script, not the author's count) and confirmed 0 matches in the actual effectiveness-standard sections; a broader whole-file scan found 3 incidental, pre-existing, out-of-scope 4-grams (generic English phrasing, unrelated sections, not touched by this PR).

AC2 verification

All mandated elements present and each carries a genuinely decidable "how to check" test (verified 7 of 9 directly decidable, 2 decidable-with-reasonable-judgment — acceptable for prose guidance). Manual read of all 7 rewritten passages confirms natural phrasing, no lost antecedents, and each principle still asserts the identical rule as before the rewording — this was a wording-only pass throughout.

Findings — all resolved

• Major ×2 (round 1), resolved — principle 8's spec misstatement (verified against the live agentskills.io spec page: version/author are not top-level fields, correctly re-framed as a tolerated extension); verbatim reference-model text (5 named passages, later found incomplete).
• Major (round 3), resolved — the round-1 de-verbatim fix was too narrowly scoped; round 4's mechanical sweep closed this properly, independently verified.
• Minor ×5 across rounds, resolved — size-limit misattribution, non-decidable leading-words check, "worked examples" overclaim, a bare URL failing MD034, plus the additional matches the n-gram scan caught beyond the originally-named list.
• Minor, nonActionable — 3 incidental whole-file 4-grams outside the effectiveness-standard scope, pre-existing, not part of this PR's diff.

Gates: mdlint 0 errors, docs-staleness PASS, links valid, knowledge-hub 56/56.

Verdict

Approved. Scope discipline held throughout (only 3 files, zero SKILL.md touched — clean mutex with PR #310); the license-risk concern that drove 3 remediation rounds is now genuinely closed, verified by independent reproduction rather than trust.

🤖 Independent review generated with Claude Code

[rucka]

Smoke test — review checklist applied to one existing skill

Per T2's Testing line ("review checklist applied to one existing skill as smoke test"): applied the 9-box checklist from writing-skills.mdx to packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md (head 4e91b1c).

#	Principle	Result	Evidence
1	Description = trigger	FAIL	Body identity in description (persist path, one-file-per-story rule); reach clause present but trigger branches implicit, not enumerated — a T3 target
2	Information hierarchy	PASS	151 lines, single file — disclosure not licensed; steps lead. Note: two "future composer" Composition Interface blocks are low-reach material
3	Completion criteria	FAIL	Step 8 Verify ("Caller has the state needed to continue") is a judgment call; Steps 4/6/7 end on Act with no Verify beat — a T6 target
4	Pruning / one home per meaning	FAIL	Edge Cases section restates Steps 1, 4/6, 7; Notes restate Core Rules (one-file-per-story, write-at-most-one-file) — a T6 target
5	Leading words	PASS	HALT, idempotent, compose, write-free, source of truth, handoff used consistently
6	Positive phrasing	PASS	All 4 "never" guardrails paired with an adjacent positive target
7	Co-location	FAIL	Load-bearing write-scope rule ("writes at most one file") sits in Notes, ~120 lines from Step 5 / Core Rules it governs — a T6 target
8	Constraints	PASS	name 10 + description 382 = 392 ≤ 1024 combined; frontmatter = spec fields + tolerated version/author; dataset+mirror changed in same commit
9	Eval evidence	N/A	Harness is T7; this PR's description edit is a citation removal, not a trigger rewrite

Conclusion: checklist is decidable and discriminates — 4 real findings, each already scoped to T3/T6 by the story's task breakdown (no T2 change needed). Standard usable as the T3–T6 gate.

[rucka]

Independent hunk-by-hunk review of T2b commit 175b043

Independent adversarial review, scope strictly 175b043 ("[#313] chore: T2b slim 14 mutex-excluded skills (meaning-preserving)"). The T2 content previously approved (4 rounds) was not re-reviewed. Review reconstructed from issue #313 T2b AC + diff + branch code only; no author working notes consulted.

Review Information

PR Number: #319 (commit 175b043 only)
Author: rucka
Reviewer: Independent reviewer (Claude, /pair-process-review)
Review Date: 2026-07-12
Story/Epic: #313 — task T2b
Review Type: Refactor (docs/skills text, meaning-preserving)

Review Summary

Overall Assessment

• Approved with Comments — Minor issues noted, can merge

Key Changes Summary

28 files (14 skills x dataset+mirror), +62/−98 lines, −596 words (−2.8% over the 14 dataset files; same order as the precedent pass 8ca2d8c on the other 16 skills). Cuts are: compressions of the output-only boilerplate, removal of Notes restating rules already normative elsewhere in the same file, and removal of repo-specific issue citations (#100, #104, #105).

Verification method (all checks reproduced, not trusted)

1. Baseline: the 28 files at the commit parent (4e91b1c) are byte-identical to origin/main — so hunks reviewed against the parent are hunks against main, per AC.
2. Hunk-by-hunk, every removed passage traced to same-file survival (post-state via git show 175b043:<path>). Full trace below.
3. Mirror consistency: diff-of-diffs — dataset hunks vs .claude/skills/pair-* hunks after reversing the name-prefix transform (pair-capability-/pair-process-/pair-next) — byte-identical. Full post-state pairs differ only in pre-existing trailing-slash normalization of directory links (present on main, untouched by this commit).
4. assess-* skills are output-only; record-decision is the sole adoption writer (no scan-mode) #224 contract test (packages/knowledge-hub/src/assess-output-only.test.ts): untouched in the commit (empty diff vs main). All its greps re-simulated on the post-state: output-only (10 skills + 10 mirrors), no $mode argument row, no auto-creation, never block, sole writer, generic persist — all pass. The disclosed reword ("It never auto-creates tech-debt items." → "No auto-creation of tech-debt items.", assess-debt Composed Skills) restores the literal no auto-creation string that the cut Notes bullet used to carry. Both phrasings are categorical prohibitions — no semantic weakening; the categorical "never" survives twice in the same file ("never a 100% auto-conversion" same sentence; "never blocks a PR (R7.2)" in the overview).
5. Citation grep over all 28 post-state files: no #NNN issue refs remain except generic #42 placeholders in write-issue examples. See Finding 1 for the R7.2 residue.
6. CI: 175b043 is the PR head; build + preview green.

Meaning-survival trace (every non-trivial cut)

Cut (file, pre-state)	Survives in same file at
assess-{ai,architecture,infrastructure,methodology,observability,stack,testing} "This skill is output-only… caller's responsibility"	reworded in place, all clauses retained
8x Step-4 Verify "This skill writes no files."	each file's Composed Skills/overview output-only statement (assess-pm: L24, L113)
assess-architecture "Persistence — writing content to target and recording the ADR —"	retained signature /record-decision(content, target, decision-metadata)
assess-code-quality "If not found, use built-in thresholds" (Step 2)	Graceful Degradation L155 (with the actual thresholds — more precise)
assess-code-quality "read-only" bullet (independent invocation)	Notes "read-only / output-only …" bullet retained
assess-code-quality + assess-debt "Resolution cascade: Path A → …" Notes	Step 1 "Resolution Cascade" sections + frontmatter descriptions
assess-debt independent-invocation output-only bullet	overview L10 ("no $mode:scan", "no auto-conversion", "never blocks a PR (R7.2)"), L21, L147, L178
assess-debt "#100 stub" note	intentional citation cut (AC)
assess-pm "assess-pm itself never writes adoption"	L10, L24, L50, L113
assess-stack "Lifecycle-spanning" note	frontmatter description + Step 4 mode branches
assess-stack / assess-testing section-ownership notes	assess-stack Step 4 L233; assess-testing Ownership row L27 + Step 4
record-decision "(each assess-* knows how to render…)"	Composition Interface "performs no per-domain rendering; the assess-* skill owns the content"
record-decision Step 4 sole-writer restatement	overview + Composition Interface invariant bullet
record-decision GD bullet: DDR with no context map → offer minimal context-map.md + first-artifact warning	Step 4 L129-130 (verbatim behavior) + Edge Cases L176
record-decision "ADR/ADL/DDR mutually exclusive" note	## Core Rule: ADR, ADL, and DDR Are Mutually Exclusive section L24
record-decision "adoption files always updated / decision without sync is incomplete"	Step 4 header "always required — single source of truth"
write-issue "developer resolves, then re-invokes"	reworded in place ("HALTs — re-invocation is idempotent"); HALT recovery semantics are the corpus-wide convention
write-issue canonical-macrostate Note	$status Arguments row L20 + entire Step 6 (incl. both HALTs) + GD L198
bootstrap "most complex process skill"	no-op flourish, nothing to preserve
bootstrap "each phase independent / stop between phases / decisions via record-decision / gates day one"	overview L10 + Idempotent section, retained stop-between-phases bullet L310, L164 (ADL/ADR), L199 ("executable from day one")
review "(from #105)/(from #104)"	intentional citation cut (AC)
review "first skill to compose 7 atomic skills"	historical flourish, nothing to preserve
review "Phase 6 is optional / author merges via /implement Phase 4"	overview L10 "(5 review + 1 optional merge)" + Step 5.4 options 1/2 (verbatim behavior)

No rule, step, argument-table row, output element, HALT, or edge case is lost. No Arguments table or Output Format block is touched.

Business Value Validation

Completes corpus coverage of the slimming pass now that the #310 mutex is lifted; keeps dataset/mirror sync and the #224 conformance contract intact. Matches the T2b scope: mechanical completion, not a rewrite.

Code Review Checklist (applicable subset — docs-only change)

• Requirements met — all 4 T2b AC verified (AC4 with the caveat in Finding 1)
• Behavior preservation (refactor) — every cut redundant in the same file (trace above)
• Readability — compressed phrasings remain unambiguous
• Style — consistent with precedent pass 8ca2d8c in kind and scale
• No dependencies, no API/DB surface — N/A
• Security: N/A (markdown skill text only; no secrets, no executable content)
• Performance: N/A

Testing Review

#224 contract test: untouched in commit; all greps re-simulated on post-state: PASS
CI (build, preview) on head 175b043: PASS
Mirror diff-of-diffs (28 files, prefix transform): identical

Detailed Review Comments

Positive Feedback

• The disclosed test-driven guard interaction (reword retained text rather than touching the conformance test) is exactly the right call — the guard did its job and the contract string survives with equivalent semantics.
• Dataset/mirror discipline is exact: not a single hunk diverges under the transform.
• The GD-bullet cut in record-decision looked like a lost edge case at first sight; it is in fact triple-stated (Step 4, Edge Cases, GD) and the two normative copies survive.

Issues to Address

Minor Issues 💡

• 1. Residual repo-specific requirement-ID citations (R7.2) — dataset/.skills/capability/assess-debt/SKILL.md:10,178, capability/write-issue/SKILL.md:206, process/review/SKILL.md:197 (+ mirrors, 8 occurrences). This PR's own citation rule (commit 4e91b1c: KB-shipped skills "must not reference this repo's own ADRs, decision-log entries, or issue-tracker numbers") is the basis of T2b's AC "citation grep re-confirmed clean". R7.2 resolves only via Pair's adr-009-assess-output-only.md / story assess-* skills are output-only; record-decision is the sole adoption writer (no scan-mode) #224 — a dangling reference for any installing project. The grep is clean for #NNN issue refs (this commit removed Code review with skills (/review, /verify-done) #100/Assessment skills (8 assess-* with resolution cascade) #104/Remaining capability skills + /verify-adoption + /next update + prompt deprecation #105 and even one R7.2 occurrence), but these remain. Removing the bare (R7.2) citations is trivially meaning-preserving (the prohibitions themselves stay) and does not break the contract test (it greps no auto-creation / never block, not R7.2). Recommendation: strip (R7.2) in these 3 files (+ mirrors) either in this PR or fold into T3–T6, which will rewrite these files anyway. Pre-existing on main — not introduced by this commit — hence Minor, non-blocking.

Nits (non-actionable, reported for transparency)

• 2. Prose↔test literal coupling (assess-debt/SKILL.md:21 ↔ assess-output-only.test.ts grep no auto-creation): future meaning-preserving rewordings can fail the guard, as happened here. By design — that is what a conformance guard is for; no action in this commit's scope.
• 3. Mirror transform includes trailing-slash normalization on directory links (5 of 14 pairs), beyond the pure name-prefix rule. Pre-existing on main and byte-untouched by this commit; fixing it here would violate the commit's meaning-preserving scope.

Risk Assessment

Risk	Impact	Probability	Mitigation
Latent meaning loss in a cut	Low	Low	Full same-file survival trace above; #224 guard green
Dataset/mirror drift	Low	Very Low	Diff-of-diffs identical; guard test covers mirrors

Tech Debt

• Finding 1 (R7.2 citations) is pre-existing corpus debt surfaced by this review — candidate for deliberate promotion or absorption into T3–T6. Nothing new introduced by the commit.

Adoption Compliance

Docs-only change: no new dependencies, no new technical decisions → no ADR required. Templates followed (commit format, branch naming). Inline check level — no non-conformities.

---

Verdict: Approved with Comments — 0 Critical / 0 Major / 1 Minor (+2 non-actionable nits). All 4 T2b acceptance criteria verified met (AC4 met for issue-number citations; R7.2 residue noted as pre-existing). Merge remains human-gated per workflow.

[rucka]

T2b remediation — review #319 (comment)

Finding	Status	Fix
1 (Minor) — residual repo-specific (R7.2) citations	Fixed	fea700d — stripped all 8 occurrences (assess-debt ×2, write-issue ×1, review ×1, dataset + mirrors). Rules kept verbatim, only the parenthetical removed. Corpus-wide grep R7 over dataset + .claude/skills now clean — no occurrences beyond the 8 listed.
2	Acknowledged (nonActionable, by-design)	—
3	Acknowledged (nonActionable, pre-existing)	—

Gates re-run after fix: knowledge-hub tests 80/80 (incl. assess-output-only.test.ts — confirmed unaffected) + check:links valid, mdlint:check pass, docs:staleness PASS (35 skills, 8 commands in sync). Pre-push hook gates passed on push.

[rucka]

T2b remediation verified — Approve

Re-reviewed remediation commit fea700d ("[#313] fix: strip repo-specific R7.2 citations from skills"), the fix for Finding 1 of the T2b hunk-by-hunk review. Independently reproduced, not trusted:

• Only the parentheticals removed. Word-level diff (--word-diff) shows exactly 8 token changes, every one the removal of (R7.2): PR** (R7.2).→PR**. (×2), PR (R7.2).→PR. (×4), auto-conversion (R7.2).→auto-conversion. (×2). No other token touched — the rules around each citation are verbatim (debt never blocks / no HALT / no auto-create; deliberate tech-debt promotion).
• 4 dataset + 4 mirror, across assess-debt (2 lines), review (1), write-issue (1) — matches Finding 1 exactly.
• Corpus R7 grep = zero across dataset/.skills + .claude/skills.
• Dataset↔mirror consistent — commit hunks byte-identical modulo the name-prefix transform.
• assess-output-only.test.ts untouched — byte-identical to origin/main; assess-* skills are output-only; record-decision is the sole adoption writer (no scan-mode) #224 contract strings (no auto-creation, never block) still present in the post-state.

Finding 1 (the sole Minor) is resolved with no meaning loss and no new findings. All 4 T2b acceptance criteria now met cleanly, including the citation-clean AC.

Verdict: Approve. Merge remains human-gated.

[rucka]

Code Review — PR #319 (canonical /pair-process-review run)

Produced by /pair-process-review (6-phase process; Phase 6 merge deliberately not run — merge is human-gated). Independent skill-run: reconstructed from story #313 (T2 + T2b AC) + the diff + branch code only. Gates re-executed on the head, not trusted from prior comments.

Review Information

• PR: [#313] docs: skill authoring effectiveness standard (task T2) #319 — [#313] docs: skill authoring effectiveness standard (task T2)
• Author: rucka
• Reviewer: Independent reviewer (Claude, /pair-process-review)
• Review Date: 2026-07-13
• Story/Epic: Skill corpus effectiveness: trigger descriptions, shared references, progressive disclosure, sharpened criteria, router fixes, authoring standard + eval #313 (tasks T2 authoring effectiveness standard + T2b slim 14 mutex-excluded skills)
• Review Type: Documentation (T2) + Refactor / meaning-preserving (T2b)
• Head reviewed: fea700d

Review Summary

Overall Assessment

• Approved with Comments — Minor issues noted, can merge

Key Changes Summary

34 files, +279/−119. Two disjoint slices in one PR:

• T2 — extends writing-skills.mdx with a 9-principle effectiveness standard (each with a decidable "How to check" test) + a review checklist usable as the T3–T6 gate; condenses the 9 points into skills-guide.md (dataset + root mirror); records ADR-010. Skill mechanics kept verbatim; zero SKILL.md behavior changed by T2.
• T2b — meaning-preserving slim of the 14 previously mutex-excluded skills (10 assess-*, record-decision, write-issue, bootstrap, review) across dataset + mirror (28 files) + a checkpoint citation fix (4e91b1c, #256 removed) + R7.2 citation strip (fea700d).

Business Value Validation

Confirmed. T2 lands the standard that gates the later structural passes (T3–T6); T2b completes the corpus-wide slimming now that #310's mutex is lifted. Both match the story's task breakdown; scope is disciplined (no forward-task work leaked in).

Phase 1 — Validation

PR open and mergeable; story #313 loaded with AC + task breakdown. Review type classified docs+refactor. Proceeded.

Phase 2 — Technical Review

Quality gates (re-run on fea700d, not trusted)

knowledge-hub test  : vitest 80/80 PASS (incl. assess-output-only.test.ts — 24 tests, the #224 output-only contract)
check:links         : all markdown links valid
mdlint:check        : 5/5 packages clean
docs:staleness      : PASS — 35 skills, 8 commands in sync
website test        : 20/20 PASS

Meaning-survival trace (T2b — every high-risk cut independently re-verified in the post-state, not trusted from the author trace)

Cut	Verified survives in same file
assess-code-quality Step 2 Verify "If not found, use built-in thresholds"	Graceful Degradation L155 — with the concrete thresholds (cyclomatic > 10, fn > 50, file > 300, cov > 70%), strictly more precise
assess-code-quality + assess-debt "Resolution cascade" Notes bullet	Step 1 Resolution Cascade sections (Path A/B[/C]) + frontmatter descriptions
record-decision "ADR/ADL/DDR mutually exclusive"	## Core Rule: ADR, ADL, and DDR Are Mutually Exclusive (L24)
record-decision DDR-with-no-context-map GD bullet	Step 4 L129–130 + Edge Cases L176
record-decision "adoption always updated / single source"	overview L10, Core Rule L29, Step 4 L105
assess-stack "Lifecycle-spanning" / "Section ownership" Notes	frontmatter + ## Lifecycle Modes (L31) + Step 0; ## Section Ownership (L195), L173–174, L249
bootstrap "stop between phases / day one / idempotent" Notes	Notes L310, Idempotent section L285, L199 ("executable from day one")
8× Step-4 Verify "This skill writes no files."	each file's Composed-Skills/overview output-only statement

No rule, step, argument row, output block, HALT, or edge case is lost. No Arguments table or Output Format block touched.

Mirror consistency

Diff-of-diffs (dataset hunks vs .claude/skills/pair-* hunks, reversing the name-prefix transform): byte-identical (56 changed lines each side). The assess-output-only.test.ts guard (which greps both dataset and mirror) is green, enforcing sync at test time.

Design-rule / standards scan

Markdown-only change; no code, no dependencies, no API/DB surface. No Design Rule (DR-*) applies. Positive-phrasing, co-location, and pruning principles the PR documents are themselves respected by the T2b cuts (they remove sediment/duplication, not load-bearing rules).

Phase 3 — Adoption Compliance

• New technical decision → ADR present. ADR-010 records the standard (Decision / Rationale / 3 alternatives / Consequences / Adoption Impact / References). Satisfies the "record decisions" rule → no missing-ADR HALT.
• Portability rule respected. No assistant-specific frontmatter added; T2b touches body prose only. The standard itself codifies the core-frontmatter-only rule (principle 8).
• No dependency/tech-stack delta → nothing for assess-stack. Templates (ADR, commit [#313] type:, branch docs/#313-authoring-standard) followed.
• Citations clean. Corpus grep for R7.2, #100, #104, #105, #256 over dataset + mirror post-state: zero (only generic #42 example placeholders remain). Satisfies T2b's citation-clean AC.

Degradation: inline (verify-adoption/assess-stack not required for a docs+refactor change with no stack delta).

Phase 4 — Completeness (DoD vs #313 T2 + T2b)

T2 · AC2 — all mandated elements present in writing-skills.mdx: description=trigger, information hierarchy + progressive disclosure, checkable+exhaustive completion criteria, the four pruning tests (no-op / sediment / duplication / single source of truth), leading words, positive phrasing, co-location, the agentskills.io constraints, portability. Each principle carries a decidable "How to check". Review checklist present and usable as the T3–T6 gate (AC2's stated bar). ADR recorded. Condensed mirror in skills-guide.md (dataset + root) consistent under the name transform. Met.

Note: the PR is more accurate than AC2's wording — AC2 calls "name+description ≤1024" an agentskills.io constraint; the PR correctly distinguishes the spec's separate caps (name ≤64, description ≤1024) from Pair's stricter combined ≤1024 bound. This is the round-1 remediation, not a defect.

T2b · AC — 14 skills hunk-verified against origin/main; every non-trivial cut traced to same-file survival (above); dataset+mirror byte-consistent under transform; citation grep clean. Met.

Story-level DoD items not covered here (trigger eval, next routes every skill, all-AC) belong to T1/T3/T7 and are correctly out of this PR's scope — #313 is an umbrella delivered one-PR-per-task.

Tech Debt (assess-debt — output-only, surfaced not blocked)

• No new debt introduced.
• Pre-existing corpus nits surfaced: prose↔test literal coupling (assess-debt prose ↔ assess-output-only.test.ts greps) — by design (that is what a conformance guard is for); mirror name-transform also normalizes trailing slashes on some directory links — pre-existing on main. Neither is introduced by this PR.

Detailed Review Comments

Positive Feedback

• The standard is genuinely decidable, not aspirational — every principle ends in a check two reviewers couldn't disagree on. That is what makes it a usable T3–T6 gate rather than prose.
• Round-1 spec correction (separating the spec's per-field caps from Pair's combined bound; version/author reframed as a tolerated extension) is precise and honest about where Pair diverges from agentskills.io.
• T2b cut discipline is exact: every removed sentence is redundant elsewhere in the same file; the assess-code-quality fallback even survives in a more precise form.

Issues to Address

Minor Issues 💡

• .pair/adoption/tech/adr/adr-010-...md:7 — stale numbering-rationale note. The note reads "adr-009 exists on an unmerged branch … this ADR takes the next free number … Renumber to 009 only if that branch is abandoned." As of now main carries adr-009 (merged via [#224] refactor: assess-* output-only; record-decision sole adoption writer #310) and adr-011/012/013, so adr-010 is a valid, collision-free gap-fill — but it is no longer "the next free number", and the "renumber to 009" instruction is moot. Impact: none functional (010 is unique; docs-staleness and links green); purely an out-of-date explanatory note. Recommendation: drop the note (or trim to "fills the 010 gap between merged 009 and 011") — non-blocking; fine to fold into a later ADR-hygiene pass.

Nits (nonActionable — reported for transparency)

• Prose↔test literal coupling (assess-debt/SKILL.md ↔ assess-output-only.test.ts greps no auto-creation / never block): by design — a conformance guard; future rewordings that trip it are the guard doing its job.
• Mirror transform trailing-slash normalization on some directory links: pre-existing on main, byte-untouched here; "fixing" it would exceed the meaning-preserving scope.

Risk Assessment

Risk	Impact	Probability	Mitigation
Latent meaning loss in a T2b cut	Low	Low	Full same-file survival trace re-verified in post-state; #224 guard green
Dataset/mirror drift	Low	Very Low	Diff-of-diffs byte-identical; guard test covers both copies
Standard's external-spec claims drift from agentskills.io over time	Low	Low	Spec claims already remediated + independently checked in a prior round; ADR cites the source

Verdict

Approved with Comments — 0 Critical / 0 Major / 1 Minor (+2 nonActionable nits). All T2 and T2b acceptance criteria verified met; all quality gates independently re-run green on fea700d. The single Minor (stale ADR numbering note) is non-blocking. Merge remains human-gated (Phase 6 not run).

🤖 Canonical review generated with Claude Code via /pair-process-review

[rucka]

Remediation — canonical /pair-process-review finding (Minor)

Finding	Status	Fix
ADR-010 numbering note factually stale (main progressed to adr-013, so "takes the next free number" / "renumber to 009 if abandoned" reads as if 010 were the highest)	Fixed	e84304b — reworded the note to state plainly that adr-010 is valid and collision-free (adr-009 and adr-011–013 all exist on main); dropped the speculative renumber-to-009 clause. Decision content unchanged. No dataset mirror of this ADR exists (only generic adr-template/adr-process KB files), so single-file edit.

Before: > 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.
After: > Numbering note: `adr-010` is a valid, collision-free number — `adr-009` and `adr-011` through `adr-013` all exist on main.

Gates green: knowledge-hub tests 80/80 + check:links valid, mdlint:check pass, docs:staleness PASS (35 skills, 8 commands in sync). Pre-push hook passed.