Wire template-override resolution into skills (docs already claim it works — it doesn't)

[rucka]

Story Statement

As a Pair-adopting team
I want the template-override mechanism the docs already describe (.pair/adoption/tech/templates/<name>-template.md shadows the KB default) to actually work — skills resolve the project's override before falling back to the KB template — instead of silently ignoring it
So that a project can genuinely customize its PR/commit/story/ADR/etc. templates without any skill quietly using the unmodified KB default

Where: 15 SKILL.md files (dataset + installed mirrors) that link to collaboration templates; apps/website/content/docs/customization/templates.mdx

Epic Context

Parent Epic: None — standalone (closest is #213 "Skill marketplace + Quickstart + external KB scaffold", but this is a correctness gap in an already-documented customization mechanism, not marketplace/scaffold work)
Status: Refined
Priority: P1 (Should-Have) — active doc/behavior mismatch, not a hypothetical gap

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Background (investigation, 2026-07-13)

apps/website/content/docs/customization/templates.mdx (landed in #125) already documents the override mechanism and claims: "The AI reads adoption files first, so it will pick up your custom templates automatically." This is false today. Grepped every SKILL.md in packages/knowledge-hub/dataset/.skills/** that links to a collaboration template (15 files, ~35 link occurrences, 13 distinct template files) — every single one hardcodes a relative markdown link straight to the KB path (e.g. implement/SKILL.md:294 → [PR template](../../../.pair/knowledge/guidelines/collaboration/templates/pr-template.md)). Zero contain adoption/tech/templates, a ## Templates check, or any override logic. Meanwhile these same skills do actively check way-of-working.md for other overridable concerns (PM tool, state mapping, merge strategy) — the "check adoption before KB default" pattern is well-established elsewhere in the skill layer, it was just never wired up for templates.

Anyone who followed the docs today, created .pair/adoption/tech/templates/pr-template.md, and expected it to be used: it is silently ignored, no error, skills keep using the KB default. This is a live discrepancy between documentation and behavior, not a future feature request.

Also found while auditing: templates.mdx lists only 13 "official" templates but the KB ships 17 template files (missing from the doc: checkpoint-template.md, manual-test-case-template.md, manual-test-report-template.md, context-map-template.md, subdomain-context-template.md, bounded-context-template.md); and branch-template.md is referenced by zero skills (orphaned — no skill links to it today).

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a project has NOT created any template override
   When any of the 15 affected skills needs a template
   Then it resolves to the KB default path exactly as today — zero behavior change for the common case (idempotent, no override present).

2. Given a project creates .pair/adoption/tech/templates/<name>-template.md (matching one of the 17 KB template filenames)
   When a skill that uses that template runs
   Then it resolves and uses the project's override file instead of the KB default — verified for at least one skill per template category (process-composed template like pr-template.md via /pair-process-implement, and capability-composed like adr-template.md via /pair-capability-record-decision).

3. Given the resolution logic
   When implemented
   Then it is a single shared instruction (not duplicated 35 times) that each of the 15 skills references — a file-existence check on the adoption path first, KB path as fallback. No parsing of a ## Templates markdown section required for resolution to work (avoids a second source of truth going out of sync with the actual override files on disk).

4. Given way-of-working.md's ## Templates section (already proposed by templates.mdx)
   When a project overrides a template
   Then the section serves as a human-readable audit trail/record of intent — not the resolution trigger itself (the file-existence check is authoritative).

5. Given templates.mdx
   When this story lands
   Then it lists all 17 shipped templates (not 13), the override mechanism's description matches the actual implemented resolution logic, and the orphaned branch-template.md is either wired into a consuming skill or explicitly noted as reference-only (not silently left inconsistent).

Business Rules

• Adoption override always wins over the KB default when present — no partial/hybrid resolution.
• Resolution is file-existence based, not dependent on way-of-working.md prose being present or accurate.
• No new CLI code required — pair-cli install/update already treat .pair/adoption/ as untouched/preserved; this is a skill-instruction change, not a install/update mechanism change.

Edge Cases and Error Handling

• Override file exists but is malformed/empty: skill uses it as-is (same trust level as any adoption file) — not this story's concern to validate template content.
• Override file exists for a template the skill doesn't know about (typo in filename): silently unused — acceptable, matches how unused adoption content behaves elsewhere.
• record-decision's templates (adr/adl/ddr): record-decision is one of PR [#224] refactor: assess-* output-only; record-decision sole adoption writer #310's 14 touched skills (story assess-* skills are output-only; record-decision is the sole adoption writer (no scan-mode) #224) — do not touch record-decision/SKILL.md until [#224] refactor: assess-* output-only; record-decision sole adoption writer #310 merges (mutex). Sequence this story's record-decision edit after [#224] refactor: assess-* output-only; record-decision sole adoption writer #310 lands; the other 14 affected skills have no such conflict and can proceed independently.

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Shared "Template Resolution" instruction added once, referenced by all 15 skills (dataset + installed mirrors)
• templates.mdx corrected: accurate mechanism description, all 17 templates listed, branch-template.md orphan resolved
• way-of-working.md's ## Templates section documented as audit-trail (not resolution trigger) — reflected in the KB guideline that defines it
• Code review completed and approved

Quality Assurance

• Conformance check: grep confirms zero skills still hardcode a template link without going through the resolution instruction
• Dry-run: create a real override for at least 2 templates (one process-composed, one capability-composed) in a scratch adoption dir, confirm the composing skill picks it up
• Dry-run: confirm zero override present → KB default path unchanged (no regression)

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: High
Sizing Justification: mechanical, repeated edit across 15 files (dataset + mirror = 30 files) plus one shared instruction block and one doc fix; no new CLI/runtime code. Investigation already done, no discovery left.

Sprint Capacity Validation

Sprint Fit Assessment: fits in one PR (mutex constraint on record-decision aside — see T3 below).

Story Splitting Recommendations

Not needed — small enough as one story; the record-decision mutex is handled as an internal task sequencing note (T3), not a story split.

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: none block starting; record-decision's specific edit (T3) waits for #310 (story #224) to merge.
Dependent Stories: none.
Shared Components: the 15 skills listed in T1; apps/website/content/docs/customization/templates.mdx; way-of-working.md's KB-documented ## Templates section guideline.

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: static conformance (grep for hardcoded template links bypassing the resolution instruction); live dry-run with a real override file per AC2; docs-staleness / link-check gates.
Test Data Requirements: a scratch .pair/adoption/tech/templates/ override file, discarded after the dry-run.

Notes and Additional Context

Refinement Session Insights: found while investigating (2026-07-13) whether Pair's customization model supports template overriding at all, prompted by a template-slimming analysis surfacing outdated/orphaned template references. The "check adoption before KB default" pattern already exists in these same skills for other concerns (PM tool, state mapping) — this story extends that established pattern to templates specifically, it does not invent a new mechanism.
Documentation Links: apps/website/content/docs/customization/templates.mdx (existing, to be corrected).

Technical Analysis

Implementation Approach

Technical Strategy: add one shared "Template Resolution" instruction (a short Check/Act block: does .pair/adoption/tech/templates/<name>-template.md exist? use it; else use the KB path) referenced by each of the 15 skills at their existing template-link sites, replacing the static link with the resolution step. Correct templates.mdx to match.
Key Components: the 15 SKILL.md files (dataset + mirror = 30 files); a new shared instruction (could live as a short paragraph duplicated identically across the 15 — given only 15 call sites, per-skill duplication of one short paragraph is acceptable and avoids inventing a new "shared reference file" concept ahead of story #313-T4's broader shared-reference work, which this can later fold into).
Integration Points: none beyond the skills themselves — no CLI/install changes.

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation
record-decision edit conflicts with unmerged #310	Medium	Certain if done in parallel	Sequence T3 after #310 merges (explicit task dependency)
Resolution instruction wording inconsistent across 15 skills	Low	Medium	Use one exact paragraph, copy verbatim to each site, verify via diff

Task Breakdown

Tasks inline per the task-template. One PR (T3 may land as a small follow-up PR if #310 hasn't merged yet when T1/T2 are ready).

Checklist

• T1 — Shared Template Resolution instruction + wire into 14 non-record-decision skills
• T2 — Fix templates.mdx (17 templates, accurate mechanism, orphan resolution)
• T3 — Wire record-decision (after [#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 merges)

Dependency Graph

T1 ─► T2   (docs describe the mechanism T1 implements)
T3 (independent content, sequenced by TIME not logic — waits for #310 merge)

AC Coverage

Task	AC1	AC2	AC3	AC4	AC5
T1	✓	✓	✓	✓
T2					✓
T3	✓	✓

Detailed Tasks

T1 — Shared Template Resolution instruction + wire 14 skills

Task Information — Priority: P1 · Est: 1d · Bounded Context: Adoption & Guidelines (skills)
Type: Refactoring
Description: Write one short Check/Act instruction block ("Template Resolution: does .pair/adoption/tech/templates/<name>-template.md exist? use it, else use the KB default path") and replace each hardcoded template link in the 14 skills (all except record-decision) with a reference to this resolution step, at each of their ~32 remaining link sites. Sync dataset + installed mirrors.
Acceptance Criteria: AC1-AC4; grep confirms no remaining bare template links in the 14 skills; dry-run proves override pickup + no-override-unchanged.
Files to Modify: grill, checkpoint, execute-manual-tests, design-manual-tests, write-issue, map-subdomains, map-contexts, plan-stories, refine-story, plan-initiatives, plan-epics, review, implement, plan-tasks (dataset + mirror, 28 files).
Dependencies: none.
Steps: 1) draft the resolution instruction; 2) apply to all 14 skills' link sites; 3) sync mirrors; 4) grep-verify; 5) dry-run override pickup.
Testing: static conformance grep; live dry-run per AC2/AC1.

T2 — Fix templates.mdx

Task Information — Priority: P1 · Est: 0.5d · Bounded Context: Adoption & Guidelines
Type: Documentation
Description: Correct the mechanism description to match T1's actual resolution logic (file-existence check, not "AI reads adoption files first" hand-wave); add the 6 missing templates to the "official" list (17 total); resolve branch-template.md's orphan status (either link it from a consuming skill's branch-naming step, or explicitly document it as reference-only, human-consulted, not skill-composed).
Acceptance Criteria: AC5.
Files to Modify: apps/website/content/docs/customization/templates.mdx.
Dependencies: T1 (describes what T1 builds).
Testing: docs-staleness; link check.

T3 — Wire record-decision (sequenced after #310 merges)

Task Information — Priority: P1 · Est: 0.25d · Bounded Context: Adoption & Guidelines
Type: Refactoring
Description: Apply the same Template Resolution instruction to record-decision/SKILL.md's adr/adl/ddr template link sites (3 sites), dataset + mirror. Must NOT start until PR #310 (story #224) has merged, since record-decision/SKILL.md is one of #310's 14 touched files — editing it in parallel risks a conflicting/overwritten merge.
Acceptance Criteria: AC1, AC2 (ddr/adr/adl override pickup verified).
Files to Modify: record-decision/SKILL.md (dataset + mirror).
Dependencies: #310/#224 merged.
Testing: dry-run override pickup for one of adr/adl/ddr.