[#313] refactor: skill naming taxonomy — analyze-* for report skills (task T8)

[rucka]

Summary

What Changed

Task T8 of story #313 (folded into #313, one PR). Disambiguates the skill verb that assess-* was overloading, and renames the two report skills to a new analyze-* verb.

Three clean verbs, one operation each:

• verify-* — conformance pass/fail (verify-quality, verify-done, verify-adoption). Unchanged.
• assess-* — evaluate options + PROPOSE an adoption choice (the 8 decision skills). Unchanged.
• analyze-* (NEW) — analyze + REPORT only; proposes no decision, never blocks a PR.

Renames (rename-only, no behavior change — both remain output-only per ADR-009):

• assess-debt → analyze-debt
• assess-code-quality → analyze-code-quality

Skill count stays 35 (rename, not add/remove).

Why This Change

assess-* conflated "propose an adoption decision" with "analyze and report only", blurring reader/router expectations and making the assess-* descriptions near-clones (a known #313 finding). Splitting out analyze-* gives each verb a single, predictable effect.

Story Context

Story: #313 — Skill corpus effectiveness. Task: T8 (added to the story body: checklist, AC-coverage row, detailed task).
Acceptance Criteria: AC2 (guideline documents the verb tripartition), AC8 (all consistency gates green; dataset + mirror byte-consistent under the transform).

Changes Made

Implementation Details

• Renamed skills (dataset + .claude mirror, git mv → history preserved at 97% similarity): analyze-debt, analyze-code-quality. Updated each SKILL.md name, H1 title, leading description verb (Assesses→Analyzes), and the Composition-Interface self-reference.
• Router (next, dataset + mirror): catalog rows + suggestion cascade row 14, category set to Analysis.
• Composition (/review, dataset + mirror): required composed skill /analyze-debt in the description, Composed-Skills table, Phase 4.2, and degradation note.
• skills-guide (dataset + root mirror): new Analysis Skills group; Verification Skills now only the 3 verify-*; manage-flags moved to Operational; old Code Quality bucket dissolved; added the missing State and Handoff (checkpoint) bucket so the capability count is honest (24→25, matching the Skill-Types table and the corpus); directory diagram + Navigation example updated; Migration Notes entry added (old→new dir paths + installed command names + rationale).
• skills-catalog.mdx (frozen path, content-only): new Analysis Capabilities section with the 2 renamed rows (removed from Assessment); /review Composes cell updated; "Last updated" bumped.
• concepts/skills.mdx: composition example /assess-debt → /analyze-debt.
• writing-skills.mdx: added verify-/assess-/analyze- rows to the naming table + a one-line 3-verb rule.
• eval/trigger-prompts.json: family assess-report → analyze-report; skills/expected/near_miss_for updated.
• conformance test (assess-output-only.test.ts): assess-* loop narrowed to the 8; new coverage that analyze-* are output-only (dataset + mirror) and analyze-debt has no scan-mode.
• ADL: .pair/adoption/decision-log/2026-07-13-skill-naming-verb-taxonomy.md records the tripartition + the two renames; cross-linked from the skills-guide Migration Notes.

Files Changed

• Renamed (4): capability/analyze-debt/SKILL.md, capability/analyze-code-quality/SKILL.md (dataset) + their .claude/skills/pair-capability-analyze-* mirrors.
• Modified: next/SKILL.md, process/review/SKILL.md (dataset + mirrors); .pair/knowledge/skills-guide.md + dataset/.pair/knowledge/skills-guide.md; skills-catalog.mdx, concepts/skills.mdx, writing-skills.mdx; eval/trigger-prompts.json; assess-output-only.test.ts.
• Added: .pair/adoption/decision-log/2026-07-13-skill-naming-verb-taxonomy.md.

Testing

Gates run natively in the worktree (node_modules installed; content-ops built):

docs:staleness            PASS — 35 skills, 8 commands in sync
skills:conformance        PASS — 35 skills conformant (frontmatter, size, pointers)
knowledge-hub test        PASS — 101 tests (incl. assess-output-only: 24)
check:links               PASS — all markdown links valid
mdlint:check              PASS (turbo + root); changed .pair/.claude files 0 errors

Whole-repo residual grep for assess-debt/assess-code-quality: zero live/operational refs. Remaining hits are point-in-time history only (see Reviewer Notes).

Quality Assurance

• Dataset ↔ mirror byte-consistent under the name-prefix transform for both renamed pairs (verified by diff).
• No functional change: analyze-* skills keep the identical output-only algorithm (ADR-009 still governs their contract).

Reviewer Notes (please confirm the judgment calls)

Points beyond the literal "rename + update refs", flagged for your call:

1. Description leading verb changed Assesses→Analyzes (and H1 … Assessment→… Analysis) in the 2 renamed skills, for coherence with the new verb. Generic English "assess/assessment" inside the algorithm bodies and the TECH DEBT ASSESSMENT output header were left as-is (they describe the operation, not the skill-name verb).
2. Router category for the 2 rows set to Analysis (was Assessment).
3. skills-catalog — created a new Analysis Capabilities section (rather than leaving them under Assessment Capabilities), so the "all assess-* are output-only" section intro stays accurate.
4. skills-guide checkpoint — added a "State and Handoff (1)" bucket while reorganizing categories. checkpoint was previously absent from the guide's Full Catalog (count said 24 while the Skill-Types table and corpus say 25); this fixes that pre-existing drift. In scope of "category coherence" but strictly beyond the rename.

Left as history (old names retained — not live refs)

Not changed, intentionally, as immutable point-in-time records (same convention as the Migration Notes):

• .pair/adoption/tech/adr/adr-009-assess-output-only.md — Accepted ADR dated 2026-07-12; documents the decision when the skills were still named assess-debt/assess-code-quality. The new ADL states it complements, does not amend ADR-009. If you'd prefer a "superseded-in-part / renamed → analyze-*" note added to ADR-009, say so.
• packages/knowledge-hub/eval/results/2026-07-12-baseline.md — dated eval-run snapshot; renaming would falsify what that run tested.
• (Also intentional: the new ADL + the two skills-guide Migration Notes entries, which document the old→new mapping; and a one-line explanatory comment in the conformance test.)

Dependencies & Related Work

• Follows: [#224] refactor: assess-* output-only; record-decision sole adoption writer #310 (assess-* skills are output-only; record-decision is the sole adoption writer (no scan-mode) #224) merged; conceptually after T1 (router/catalog, [#313] fix: router/catalog + correctness fixes (task T1) #325).
• Related: part of Skill corpus effectiveness: trigger descriptions, shared references, progressive disclosure, sharpened criteria, router fixes, authoring standard + eval #313 — this is task T8, delivered in the story's single PR.

Refs #313

🤖 Generated with Claude Code

[rucka]

Code Review — PR #327

Review Information

PR Number: #327
Title: [#313] refactor: skill naming taxonomy — analyze-* for report skills (task T8)
Author: (foomakers/pair)
Reviewer: Independent reviewer (automated, blind to author working notes)
Review Date: 2026-07-13
Story/Epic: #313 — Skill corpus effectiveness (task T8)
Review Type: Refactor (rename-only migration + doc/category coherence)
Head commit: b18272d

Review Summary

Overall Assessment

• Approved with Comments — complete, correct, all gates green; two non-blocking minor notes.

Key Changes Summary

Introduces a third capability-skill verb, analyze-* (analyze + report only), alongside verify-* (conformance) and assess-* (the 8 decision skills), and renames the two report skills assess-debt→analyze-debt, assess-code-quality→analyze-code-quality across the dataset and the .claude mirror (git-mv, history preserved). Every cross-reference is moved in lockstep: router catalog + cascade, /review composition contract, skills-guide categories + Migration Notes, skills-catalog, concepts/writing-skills docs, eval trigger-prompts, and the #224 conformance test. A new ADL records the taxonomy. Rename-only; no behavior change (ADR-009 still governs the output-only contract). Corpus stays at 35.

Business Value Validation

Delivers T8 against AC2 (guideline documents the verb tripartition) and AC8 (all consistency gates green; dataset + mirror byte-consistent). Sharpens router/reader/eval differentiation the umbrella story targets — the two report skills leave the assess-* near-clone cluster.

Verification Performed (independent)

All gates run natively from a detached worktree pinned to origin/chore/#313-t8-analyze-rename (deps installed, @pair/content-ops built):

Gate	Result
docs:staleness	PASS — 35 skills, 8 commands in sync
skills:conformance	PASS — 35 skills conformant (frontmatter portability, size, pointers)
@pair/knowledge-hub test (vitest)	PASS — 101 tests (incl. assess-output-only: 24)
check:links	PASS — all markdown links valid
mdlint:check (turbo + root)	PASS

Additional checks:

• Renames (4 dirs): git-mv at 97% similarity; git log --follow shows history preserved back through assess-* skills are output-only; record-decision is the sole adoption writer (no scan-mode) #224. name: frontmatter, H1, and Composition-Interface self-refs updated in all four. No leftover old dirs (dataset or mirror).
• Zero residual LIVE old-name refs: whole-repo grep for assess-debt / assess-code-quality / pair-capability-assess-* returns only point-in-time history — the new ADL, ADR-009, the skills-guide Migration Notes (both copies), the explanatory conformance-test comment, and eval/results/2026-07-12-baseline.md (incl. its ### assess-report heading). No live ref in any router catalog, composition contract, how-to, llms.txt, or doc link.
• Router (next, dataset + mirror): the 2 catalog rows + cascade row 14 renamed, category Analysis; count stays 35; checkpoint (row 7) and grill still routable — no regression to [#313] fix: router/catalog + correctness fixes (task T1) #325/T1.
• Composition (/review, dataset + mirror): description, Composed-Skills table, Phase 4.2 (all three beats), Step 5.1 Tech-Debt line, and the degradation note all say /analyze-debt; no dangling /assess-debt. Step 6.1–6.6 numbering intact (no [#313] fix: router/catalog + correctness fixes (task T1) #325 regression).
• skills-guide (root + dataset): new "Analysis Skills (2)"; "Verification (3)" = only the 3 verify-*; manage-flags→"Operational (6)"; "Code Quality" bucket dissolved; "State and Handoff (1)" = checkpoint; Full-Catalog header 24→25 now reconciles with the Skill-Types table (which already read 25 on main) and the arithmetic (2+8+2+3+6+2+1+1=25); directory diagram + Navigation updated; Migration Notes entry well-formed and cross-linked to the ADL.
• skills-catalog.mdx (frozen path): file MODIFIED, not moved; new "Analysis Capabilities" section; the 2 rows removed from Assessment (whose intro — "All assess-* skills are output-only: they produce a proposal (rendered adoption content + target)" — is now accurate); "Last updated" bumped; docs-staleness cross-check green.
• Mirror byte-consistency: both renamed pairs are byte-identical to their dataset source under the name-prefix transform (name: + slash-command prefixing).
• ADL: .pair/adoption/decision-log/2026-07-13-skill-naming-verb-taxonomy.md — correct location/date-naming (matches siblings); documents verify/assess/analyze tripartition + the 2 renames; "no dataset mirror" claim verified (sibling ADLs aren't mirrored either).
• Skill corpus effectiveness: trigger descriptions, shared references, progressive disclosure, sharpened criteria, router fixes, authoring standard + eval #313 body: T8 appended cleanly (checklist item, AC-coverage row, detailed task); T1–T7/T2b content intact.

Detailed Review Comments

Positive Feedback

• Textbook wide-migration hygiene: git-mv preserves history, dataset+mirror moved in the same change, byte-consistency verified, every operational cross-reference chased down, zero live residual refs.
• The taxonomy is recorded (ADL) and the forward mapping documented (Migration Notes ×2), while immutable history (ADR-009, dated eval baseline) is deliberately left intact — the right call.
• Conformance test meaningfully strengthened: the assess-* loop is narrowed to the 8 decision skills and new coverage asserts analyze-* output-only + analyze-debt scan-mode-free, in both dataset and mirror.

Minor Issues

• #313 body → AC Coverage table (T8 row) — the matrix marks T8 against AC1, but the detailed T8 task and this PR's Story Context scope it to AC2 + AC8 only. T8 preserves AC1 (router still routes 35) rather than delivering it (that was T1/[#313] fix: router/catalog + correctness fixes (task T1) #325). Internal inconsistency in the appended content; zero functional impact.
• process/review/SKILL.md:19, next/SKILL.md:52-53 (+ mirrors) — GFM table pipe alignment on the renamed rows drifts by a column (the longer analyze-* name wasn't re-padded). Cosmetic only; mdlint passes and it renders identically. Non-actionable / cosmetic.

Questions / Judgment Calls (author-flagged) — reviewer's view

1. Mixed assess/analyze inside the renamed skills (description leading verb + H1 changed to Analyze/Analysis; generic body "assess/assessment", the cascade path name "Assessment", and the TECH DEBT ASSESSMENT output header left as-is): Acceptable — concur. The verb taxonomy governs the skill name/routing signal (frontmatter name, H1, cross-refs), not every English occurrence of "assess". Purging the operation-descriptive wording would balloon the diff and risk the byte-consistency focus for no routing benefit. Optional follow-up polish: rename the user-facing TECH DEBT ASSESSMENT header to "…ANALYSIS" for full coherence — minor, not required.
2. Router category Analysis: Correct. Matches the new verb and the skills-guide "Analysis Skills" group; gates green.
3. New skills-catalog "Analysis Capabilities" section: Correct — and necessary. The "Assessment Capabilities" intro claims all its skills "produce a proposal (rendered adoption content + target)", true only of the 8 decision skills; leaving the 2 report skills under it would make that intro false. Splitting is the right call.
4. skills-guide checkpoint bucket (24→25): In scope and correct. T8's task explicitly includes "category coherence." On main the Skill-Types table already said 25 while the Full-Catalog header said 24 and omitted checkpoint entirely — a pre-existing self-contradiction. Reconciling it while reorganizing the very categories around it is justified and now arithmetically consistent. (Defensible to fold; could equally have been its own commit.)
5. ADR-009 + dated eval baseline left as history: Correct — concur. ADR-009 is an Accepted, dated record the ADL explicitly complements, does not amend; rewriting old names in a dated eval-run snapshot would falsify what that run tested. Matches the Migration-Notes convention (forward mapping in living docs, history untouched). The ADL's offer to add a "renamed → analyze-*" pointer to ADR-009 is a nice-to-have, not required.

Risk Assessment

Risk	Impact	Probability	Mitigation
Stale external references to old command names	Low	Low	Migration Notes (both copies) + ADL document the mapping; installed command names shipped via the mirror
Reader confusion from residual "assessment" wording in analyze-* bodies	Low	Low	Verb governs routing; body wording is operation-descriptive; optional header polish noted

Security / Performance / Testing-coverage / Deployment sections: N/A — documentation + skill-metadata rename; no runtime code, no dependencies, no data flow changed. Test coverage for the affected contract was extended (conformance suite).

Decision

Approved with Comments. No critical or major issues. AC2 and AC8 (T8's scope) are met; all consistency gates pass; dataset+mirror byte-consistent; history preserved; no regression to #325. The two minor notes (AC-coverage AC1 mark; cosmetic table alignment) are non-blocking and can be addressed opportunistically or waved through at the human merge gate.

[rucka]

Remediation — round 1 (commit 9e555e2)

Per finding:

• [minor] GFM table columns drift on the longer analyze-* rows (process/review/SKILL.md ~L19, next/SKILL.md ~L52-53) → re-padded both tables to aligned max-width columns (also unified pre-existing raggedness in the same two tables — the verify-adoption/assess-stack/execute-manual-tests optional rows in review, and the overflowing rows in next). Cosmetic only; mdlint still passes. — next/SKILL.md, process/review/SKILL.md + .claude/skills/pair-next, pair-process-review mirrors.
• [polish] within-skill assess→analyze consistency (judgment-call Setup & Project Management Integration #1 from round-0 review) → aligned each renamed skill's OWN action/output labels: TECH DEBT ASSESSMENT→TECH DEBT ANALYSIS; Path B/C Existing/Full Assessment→…Analysis; Re-assess?→Re-analyze?; RESULT Assessed→Analyzed; $scope/$path "Limit assessment"→"Limit analysis"; "existing/previous/last assessment"→"…analysis"; Notes "re-assesses/Quality assessment/quick assessment"→analyze/analysis. — capability/analyze-debt, capability/analyze-code-quality (dataset + mirrors).

Deliberately left as assess/assessment (generic/shared, NOT this skill's own action label):

• resolution cascade (Argument > Adoption > Assessment) — shared cascade-tier name, identical across all 10 assess-/analyze- skills; changing it here alone would break the cross-skill convention.
• Assess **Impact** (1-5) / Assess **Effort** (1-5) (analyze-debt Step 3) — generic scoring verbs for rating a dimension, not the skill's top-level action.
• Risk assessment for the remediation itself (analyze-debt Step 4) — generic domain concept.
• Severity assessment considers the project's maturity… (analyze-debt Notes) — generic dimension-judgement, parallel to "risk assessment".

Not changed (escalated): #313 checklist — T2b — coordinator asked to mark T2b done as "(#319)", but #319 is T2 ([#313] docs: authoring standard); no merged PR delivers T2b (extend slimming to the 14 mutex-excluded skills — #316 is the original pass that excluded them, #323 is templates). Left T2b [ ] to avoid a false checkmark. T1 [x] (#325) and T7 [x] (#324) reconciled as instructed. → coordinator to confirm T2b's real status/PR.

Quality gates: PASS — docs:staleness (35 skills), skills:conformance (35), pnpm --filter @pair/knowledge-hub test (101 incl assess-output-only.test.ts) + check:links, mdlint:check. Dataset↔mirror byte-consistent under the transform for both renamed pairs. Residual old-name grep: history only (ADR-009, eval baseline, Migration Notes, ADL, test comment).

→ Re-review requested.

[rucka]

Re-review of completion 9e555e2 — Approve, no open items

Independent re-review of the delta b18272d..9e555e2 (completion round on the round-0 "Approved with Comments"). Both prior findings resolved; no regressions; all gates green.

Overall Assessment: Approved. No critical/major/minor open items.

Findings resolved

1. Table alignment (round-0 finding 2) — RESOLVED. GFM columns re-padded in next/SKILL.md (Capability Skills, 25 rows) and process/review/SKILL.md (Composed Skills) + both .claude mirrors. Verified diff-by-diff: only pipe padding changed, zero cell-value changes — every skill name, category, and description string is byte-identical to b18272d. Rows now column-aligned in both dataset and mirror (the mirror re-pads independently for the wider /pair-capability-* prefixed names). mdlint green; transfer-dataset byte-consistency (29 tests) green.

2. Within-skill assess→analyze consistency (optional polish, judgment-call #1) — RESOLVED, correctly scoped. In analyze-debt + analyze-code-quality (dataset + mirror), all changed strings are the skill's own action/output labels: output header TECH DEBT ASSESSMENT→ANALYSIS, path labels Existing/Full Assessment→Analysis, Re-assess?→Re-analyze?, RESULT Assessed→Analyzed, $scope/$path/$choice arg verbs, prior-output refs, and idempotency/Notes verbs. Correct to change.

The four deliberately-left occurrences are genuinely NOT the skill's own action label — leaving each is correct:

• (a) resolution cascade (Argument > Adoption > Assessment) — verified identical across all 8 assess-* AND both analyze-* descriptions; it is the shared cascade-tier name. Changing it here alone would break the cross-skill convention.
• (b) Assess Impact (1-5) / Assess Effort (1-5) (Step 3) — generic per-dimension scoring verb, not the top-level action.
• (c) Risk assessment for the remediation itself (Step 4) — generic domain concept.
• (d) Severity assessment considers the project's maturity… (Notes) — generic dimension judgment.

Independent verification

• No NEW residual LIVE old-name refs. The delta touches only the 8 SKILL.md files. Whole-tree assess-debt/assess-code-quality hits at 9e555e2 are all point-in-time history/mapping (ADL taxonomy, ADR-009, skills-guide Migration Notes ×2, eval/results/2026-07-12-baseline.md, one conformance-test comment) — unchanged, no live router/composition/how-to ref.
• Earlier-approved rename content unchanged except these polish edits.
• Gates (detached worktree at 9e555e2, deps installed, @pair/content-ops built):

Gate	Result
docs:staleness	PASS — 35 skills, 8 commands in sync
skills:conformance	PASS — 35 skills conformant
@pair/knowledge-hub test	PASS — 101 tests (incl. assess-output-only: 24)
check:links	PASS
mdlint:check (turbo + root)	PASS

• Skill corpus effectiveness: trigger descriptions, shared references, progressive disclosure, sharpened criteria, router fixes, authoring standard + eval #313 checklist reconciled and consistent per coordinator confirmation (T1/T2/T2b/T7 [x], T3/T4/T5/T6/T8 [ ]); T2b delivered via [#313] docs: skill authoring effectiveness standard (task T2) #319's combined branch.

Verdict: Approve — no open items. Ready for the human merge gate.