chore: slim dataset templates to essential info

[rucka]

Summary

What Changed

Meaning-preserving slimming pass over the knowledge-hub dataset templates (follow-up to the skill-text slimming in 8ca2d8c). 7 verbose templates reduced to essential info; 13 already-lean templates untouched; 1 dataset↔root mirror inconsistency fixed. Root .pair/ mirrors kept byte-consistent with the dataset in the same commit.

Why This Change

Templates are load-bearing contracts (skills and humans fill them), but several carried heavy instructional fluff: duplicate mini-templates, repeated placeholder blocks, git tutorials, and prose restating KB guidelines. Slimming cuts token cost for every skill that loads them without changing the contract.

Story Context

No story — maintenance chore, same lane as 8ca2d8c.

Changes Made

Per-file ledger (words before → after)

Template	Before	After	What was cut	Why it's safe
code-review-template.md	1850	1474	4 "Review Templates for Different Types" mini-templates, "Review Quality Standards" conduct prose, code-diff example, closing prose	All sections /review Step 5.1 fills by name (Review Information, Review Summary, Code Review Checklist, Security/Testing/Documentation Review, Detailed Review Comments, Risk Assessment) intact; type emphasis kept as one condensed line; conduct standards live in collaboration guidelines
pr-template.md	1662	1431	5 "Templates for Different PR Types" mini-templates, tutorial bash block	All sections /implement Step 3.3 fills (Summary, Story Context, Changes Made, Testing) intact; every checklist section kept (implement omits non-applicable ones); type emphasis condensed to one line
commit-template.md	1327	859	5 long examples → 1 canonical, 3 "Non-Code Task Commits" examples, duplicate branch-commit example lists, anti-patterns condensed	Format, types table, TDD red/green/refactor patterns, subject/body/footer rules, story/task/bug reference formats, squash-merge example (used by /review merge), quality checklist all intact
branch-template.md	1233	549	git command tutorials (workflow, cleanup, collaboration, troubleshooting, emergency), duplicate "Branch Naming Conventions" section, 4 per-type mini-templates, closing prose	Naming format/types/examples (the only content how-to-10 and /implement reference) intact verbatim; every H2 kept with condensed content; commit rules now point to commit-template instead of restating it
epic-template.md	1543	1339	Repeated placeholder blocks (3 metrics/2 pain points/2 personas/3 capabilities/2 themes/2 stories/2 deps → 1 + "[Repeat per …]"), risk tables to 1 row	All sections /plan-epics fills (Epic Statement, Business Value, Solution Overview, Epic Breakdown, Technical Considerations) intact; no field shape changed, only exemplar repetition removed
initiative-template.md	1801	1629	Repeated placeholder blocks (3 objectives/2 segments/2 components/2 epics → 1 + repeat note), 3 communication blocks → 1 table, risk tables to 1 row each	All content /plan-initiatives names (business rationale, scope, success metrics, risk assessment, timeline) intact; headings unchanged
markdown-templates.md (guideline)	1456	1128	Scope bullet lists, "Content Standards/Template Maintenance/Implementation Guidelines/Best Practices/Measurement" word-salad → 2 short sections	Not referenced by any skill (only linked from user-experience README); all 8 embedded template examples — the actual substance — kept verbatim
user-story-template.md	1311	1312	Nothing cut — dataset realigned to root mirror (/plan-tasks → /pair-process-plan-tasks)	Fixes a dataset↔root byte divergence dating to a6e9df2; root already had the correct published skill name

Untouched (lean already)

PRD_template (666w, 13-section contract referenced by /specify-prd), task (578w), checkpoint (288w, no root mirror by design), bounded-context (381w), context-map (383w), ddr (177w), adr (147w), adl (131w), subdomain (187w), subdomain-context (150w), manual-test-case (256w), manual-test-report (320w) — pure field/placeholder structure, nothing safe to cut.

Safety cross-checks

• Grepped all .skills/**/SKILL.md and how-to/*.md for template references and section names before cutting — every skill-referenced heading survives with identical text.
• Contract generation ([#206] AI-generated machine contract from KB templates (md → contract.json, cache-by-hash, loose fallback) #292) is hash-cached per template; contracts regenerate on change and all vocabulary/enums/field lists survive.
• H1 titles unchanged (llms.txt links by title).

Testing

• pnpm --filter @pair/knowledge-hub test — full suite 5 files / 80 tests pass + link check: all markdown links valid (prerequisite: pnpm --filter @pair/content-ops build, otherwise 2 test files fail to collect and only 45 tests run)
• pnpm --filter @pair/knowledge-hub mdlint:check — clean; touched root mirrors linted directly with markdownlint-cli2: 0 errors
• pnpm docs:staleness — PASS (35 skills, 8 commands in sync)
• Pre-push pnpm quality-gate — passed on push
• Mirror check: every touched dataset file byte-identical to its root .pair/ mirror

🤖 Generated with Claude Code

[rucka]

Code Review — PR #323

Review Information

• PR: chore: slim dataset templates to essential info #323 — chore: slim dataset templates to essential info
• Author: @rucka
• Reviewer: Independent AI reviewer (adversarial, PR + code only)
• Date: 2026-07-12
• Story: N/A — maintenance chore (same lane as 8ca2d8c skill-text slimming)
• Review Type: docs (template/KB content only)
• Head reviewed: 76e9294

Review Summary

Overall Assessment

Approved with Comments — meaning-preserving slimming verified hunk-by-hunk against every skill/how-to that consumes these templates. All load-bearing contract surface survives. Only Minor/Nit findings.

Key Changes Summary

7 templates + 1 guideline slimmed (-1993/+149 across dataset + root mirrors), 1 pre-existing dataset↔root divergence fixed (user-story-template).

Business Value Validation

Cuts token cost for every skill that loads these templates without changing what skills or humans fill in. Value claim holds.

Code Review Checklist

Functionality Review (contract safety)

• code-review-template: all sections /review Step 5.1 fills by name (Review Information, Review Summary, Code Review Checklist, Security/Testing/Documentation Review, Detailed Review Comments, Risk Assessment) survive verbatim — verified against .skills/process/review/SKILL.md:205-213 at head. Removed 4 per-type mini-templates + conduct prose are (a) condensed into one type-emphasis line, (b) restated in collaboration guidelines (team/standards.md "Code Review Standards", team/communication-protocols.md).
• pr-template: all sections /implement Step 3.3 fills (Summary, Story Context, Changes Made, Testing) survive — verified against implement/SKILL.md:294-301. Removed 5 per-type mini-templates condensed to one line, per-type emphasis retained.
• commit-template: types table (incl. build/ci referenced by the new non-code line), TDD red/green/refactor patterns, subject/body/footer rules, story/task/bug reference formats, Squash Merge example (used by /review Phase 6.2 and how-to-11), quality checklist — all intact. Removed content is exemplar repetition.
• branch-template: the canonical naming section (Standard Format <type>/<story-id>-<brief-description>, Branch Types, Naming Examples) — the only content how-to-10 and /implement reference — survives verbatim at the top. The removed "Branch Naming Conventions" H3 was a genuine internal duplicate (with divergent patterns, so removal actually reduces ambiguity). Removed git tutorials are pure filler.
• epic-template: sections /plan-epics Step fills (Epic Statement, Business Value, Solution Overview, Epic Breakdown, Technical Considerations) intact — verified against plan-epics/SKILL.md:107-108. No field shape changed; repeated exemplar blocks → [Repeat per …].
• initiative-template: everything /plan-initiatives names (business rationale, scope, success metrics, risk assessment, timeline) intact; Communication Plan heading preserved, prose blocks → equivalent table (all three levels, same fields).
• markdown-templates.md: referenced only by user-experience README + llms.txt (by H1 title, unchanged) — claim verified by repo-wide grep. All 8 embedded template examples untouched.
• user-story-template (dataset only): verified as a genuine pre-existing dataset↔root divergence dating to a6e9df2 (/plan-tasks vs /pair-process-plan-tasks); root already correct, PR aligns dataset to root. Correct direction (published skill name).
• No anchor links anywhere in the repo point to removed section headings (repo-wide grep for the removed heading slugs: no hits).

Code Quality Assessment

• Replacement lines preserve do/don't semantics (anti-patterns, atomic-commit principles) rather than deleting them.
• H1 titles unchanged (llms.txt links by title).

Technical Standards Compliance

• Mirror discipline: all 9 touched dataset↔root pairs byte-identical at head (verified by hash); no root file touched without its dataset twin; the one dataset-only change (user-story) is the divergence fix, by design.
• Scope: exactly 15 files, all templates + mirrors. The 6 prettier-drift files mentioned as discarded are NOT in the diff — confirmed.
• No new dependencies, patterns, or technologies → no ADR required (Phase 2.3 skip; consistent with 8ca2d8c precedent on main).

Security Review

• No code, no secrets, no executable surface. Content-only change. N/A.

Testing Review

Re-ran gates independently in a detached worktree at 76e9294:

• vitest run (@pair/knowledge-hub): 5 files / 80 tests passed (after building @pair/content-ops)
• check:links: all markdown links valid
• pnpm docs:staleness: PASS — 35 skills, 8 commands in sync
• mdlint:check: clean

Note: PR body claims "45 tests pass" — 45 is the count when 2 suites (check-broken-links.test.ts, transfer-dataset.test.ts) silently fail to collect because @pair/content-ops isn't built. Full suite is 80. See Minor issue 2.

Documentation Review

• PR description is exemplary: per-file ledger (before/after word counts, what was cut, why safe) is exactly the evidence an independent reviewer needs for a slimming PR.

Detailed Review Comments

Positive Feedback

• The safety cross-check methodology stated in the PR (grep skills/how-tos for section names before cutting) is verifiable and checks out on re-derivation.
• Removing the duplicate "Branch Naming Conventions" section eliminates a real ambiguity (the duplicate used feature/US-[story-number]-… while the canonical section uses <type>/<story-id>-…).

Issues to Address

Critical Issues ⚠️

None.

Major Issues 🔍

None.

Minor Issues 💡

1. Unlinked prose pointers — code-review-template.md:280 ("Review conduct standards: see collaboration guidelines (single source of truth)") and branch-template.md:109 ("…defined in the quality-assurance guidelines"). These are plain-text pointers, while the sibling replacements in the same PR correctly use markdown links (branch workflow links commit-template.md / pr-template.md). Impact: the link checker cannot validate prose pointers, and an agent loading only the template must guess the target path. Recommendation: link ../../collaboration/README.md (or team/standards.md) and ../../quality-assurance/README.md.
2. PR body test count inaccurate — "45 tests pass" undercounts: at head the knowledge-hub suite is 80 tests / 5 files; 45 is what vitest reports when 2 suites fail to collect (stale @pair/content-ops build). Gates genuinely pass, but the stated number suggests the authoring run had 2 suites not collecting. Recommendation: correct the PR body (or note the content-ops build prerequisite).

Questions ❓

None — the per-file ledger answered the "why" for every hunk.

Observations (non-actionable)

• /review SKILL.md Step 5.1 lists "Tech Debt" and "Adoption Compliance" report sections that have never existed as headings in code-review-template (the skill layers them on). Pre-existing on main, untouched by this PR's cuts — noted for a future template/skill alignment pass, not blocking here.
• Hotfix "Expedited Process" checkboxes and the release-branch "tag after merge" step were dropped without restatement; both are process/git-tutorial detail below template-contract level and adequately covered by the condensed type-emphasis line and quality-assurance guidelines. By design, not a loss of contract.

Risk Assessment

• Technical Risks: Low. No consumer (skill, how-to, llms.txt, anchor link) references any removed content; mirrors byte-identical; contracts ([#206] AI-generated machine contract from KB templates (md → contract.json, cache-by-hash, loose fallback) #292) are hash-cached and regenerate at runtime — no checked-in artifact to stale.
• Business Risks: None.

Tech Debt

None introduced. No debt items flagged (/assess-debt scope: content-only diff, no code).

Adoption Compliance

Level 4 (inline, chore scope): templates conform to repo template-governance conventions; mirror rule and llms.txt title-linking honored. No adoption file impact.

---

Decision: APPROVED (with comments) — 0 critical, 0 major, 2 minor. Merge is human-gated; the two Minor items can be fixed pre-merge or accepted as-is.

[rucka]

Remediation — review #323 (comment)

#	Finding	Resolution
1 (Minor)	Unlinked prose pointers in code-review-template.md / branch-template.md	Fixed in 3084ebf: code-review conduct pointer → [team standards](../team/standards.md) (has the "Code Review Standards" section, more precise than collaboration README); branch QA pointer → [quality-assurance guidelines](../../quality-assurance/README.md). Dataset + root mirrors byte-identical. Link checker validates both (check:links: all links valid).
2 (Nit)	PR body said "45 tests pass" (suite is 80 when @pair/content-ops is built)	PR body Testing section corrected: full suite 5 files / 80 tests pass, with the pnpm --filter @pair/content-ops build prerequisite noted. Confirms the authoring run had 2 suites not collecting — gates re-run at head with the build in place.
3 (Observation, non-actionable)	/review Step 5.1 lists "Tech Debt" / "Adoption Compliance" sections absent from code-review-template (pre-existing on main)	Acknowledged — tracked for a future template/skill alignment pass; no change in this PR.

Gates at 3084ebf: knowledge-hub 80/80 tests + link check ✅, mdlint ✅ (dataset + touched root mirrors), docs:staleness PASS (35 skills, 8 commands), pre-push quality-gate passed on push.

🤖 Generated with Claude Code

[rucka]

Re-review — remediation verified (head 3084ebf)

1. Finding 1 (Minor, links) — RESOLVED. Both prose pointers are now markdown links; both relative paths resolve from collaboration/templates/ (../team/standards.md → exists; ../../quality-assurance/README.md → exists); dataset + root mirror pairs re-verified byte-identical. On the author's target choice: team/standards.md is the right target — it holds the actual "Code Review Standards" section (coverage, 24h timeline, criteria, approval) plus conduct/tone standards, i.e. precisely the content the removed "Review Quality Standards" prose restated. More precise than my collaboration/README.md suggestion; accepted.
2. Finding 2 (Nit, PR body test count) — RESOLVED. Testing section now states 5 files / 80 tests with the @pair/content-ops build prerequisite — matches my independent measurement exactly.
3. Finding 3 (Nit, review SKILL.md ↔ template section drift) — acknowledged as tracked; pre-existing and out of scope, non-blocking as stated in the original review.

Final verdict: Approve. 0 critical, 0 major, 0 open minor. Merge remains human-gated.