[#313] refactor: cross-skill dedup into shared KB references (task T4)

.claude/skills/pair-capability-analyze-code-quality/SKILL.md

@@ -20,23 +20,10 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p
 
 ### Step 1: Resolution Cascade
 
-#### Path A — Existing Recent Report
+Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics — this skill uses the **report-skill variant** and has no override argument, so it starts directly at the [idempotency](../../../.pair/knowledge/skill-conventions/idempotency.md) check (no Path A/Argument-Override).
 
-1. **Check**: Is there an existing quality report for this codebase? (Check conversation context, CI artifacts, or previous analysis output.)
-2. **Skip**: If no existing report, go to Path B.
-3. **Act**: Check staleness:
-   - Has the codebase changed since the last analysis? (Use `git diff --stat` since last analysis date or commit.)
-   - If no changes → confirm existing report is still valid. Exit.
-   - If changes exist → report is stale. Present summary of changes and proceed to Path B.
-
-   > Existing quality report found ([date]). [N files changed since last analysis.]
-   > Re-analyze? (Recommended — codebase has changed.)
-
-4. **Verify**: If confirmed valid → exit. If stale or re-analysis requested → proceed to Path B.
-
-#### Path B — Full Analysis
-
-1. **Act**: Proceed to Step 2.
+- **Existing-state check (Path B)**: an existing quality report for this codebase (conversation context, CI artifacts, prior output). Staleness test: has the codebase changed since the last analysis (`git diff --stat` since last analysis date/commit)? No changes → confirm and exit. Changes exist → present the delta and proceed to full analysis.
+- **Full-analysis path (Path C)**: proceed to Step 2.
 
 ### Step 2: Read Quality Metrics Guidelines
 
@@ -116,6 +103,8 @@ For each metric group in scope, follow **check → skip → act → verify**.
 
 ## Output Format
 
+Follows the [Report Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#report-shape).
+
 ```text
 CODE QUALITY REPORT:
 ├── Scope:           [$scope — $path or full codebase]
@@ -152,15 +141,16 @@ When invoked **independently**:
 
 ## Graceful Degradation
 
-- If [code-metrics.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/code-metrics.md) is not found, use built-in thresholds (cyclomatic > 10, function > 50 lines, file > 300 lines, coverage > 70%).
+See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → fall back to built-in thresholds: cyclomatic > 10, function > 50 lines, file > 300 lines, coverage > 70%) for the standard scenarios. Additional cases:
+
 - If coverage tools are not available, skip test coverage metrics and note: "Coverage: SKIPPED — no coverage tool detected."
 - If duplication detection is not feasible (no tool), use heuristic scanning for obvious copy-paste patterns.
 - If the codebase is too large for full analysis, limit to changed files (PR scope) and note: "Partial analysis — limited to changed files."
 
 ## Notes
 
 - This skill is **read-only / output-only** — it inspects code, runs coverage (via existing test commands), but never modifies files, adoption, or the PM tool. A finding worth tracking is promoted deliberately to the backlog via `/pair-capability-write-issue` (a manual, selective act) — never auto-created.
-- **Idempotent**: re-invocation checks staleness of existing report. If codebase unchanged → confirms existing report. If changed → re-analyzes only.
+- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: staleness of the existing report (Step 1) — unchanged codebase confirms it, changed codebase re-analyzes.
 - Metrics are **health indicators, not absolute quality measures**. Context matters: business logic naturally has higher complexity, and metric targets should align with team capabilities.
 - Quality analysis is most valuable as a **trend** — individual snapshots matter less than improvement direction over time.
 - The maintainability index is a composite heuristic — it provides a single number for quick analysis but the component metrics offer more actionable insights.

.claude/skills/pair-capability-analyze-debt/SKILL.md

@@ -24,27 +24,11 @@ This skill is **output-only** — it composes no skill and writes no files. No a
 
 ### Step 1: Resolution Cascade
 
-#### Path A — Argument Override ($choice provided)
+Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics — this skill uses the **report-skill variant**, where Path B is an [idempotency](../../../.pair/knowledge/skill-conventions/idempotency.md) check against a recent output rather than an adoption file.
 
-1. **Check**: Is `$choice` provided?
-2. **Skip**: If not provided, go to Path B.
-3. **Act**: Accept the pre-identified debt item. Skip detection (Step 2). Proceed directly to Step 3 (categorization) with the single item.
-4. **Verify**: Item accepted.
-
-#### Path B — Existing Analysis
-
-1. **Check**: Is there an existing debt analysis for this codebase/PR? (Look for a recent debt report in the conversation context or PR comments.)
-2. **Skip**: If no existing analysis, go to Path C.
-3. **Act**: Present the existing analysis:
-
-   > Existing debt analysis found ([N items], [date]).
-   > Re-analyze? (Only if explicitly requested by developer.)
-
-4. **Verify**: If developer confirms existing → exit. If re-analysis requested → proceed to Path C.
-
-#### Path C — Full Analysis
-
-1. **Act**: Proceed to Step 2 (detection).
+- **Path A delta**: override argument is `$choice` (a pre-identified debt item). On accept, skip detection (Step 2) and proceed directly to Step 3 with the single item.
+- **Path B delta**: existing-state check is a recent debt report in conversation context or PR comments. Re-analysis only on explicit developer request.
+- **Path C delta**: proceed to Step 2 (detection).
 
 ### Step 2: Detect Debt Items
 
@@ -149,6 +133,8 @@ For each detected item, apply the prioritization formula:
 
 ## Output Format
 
+Follows the [Report Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#report-shape).
+
 ```text
 TECH DEBT ANALYSIS (output-only — no files or issues created):
 ├── Items Found:  [N total]
@@ -185,13 +171,13 @@ When invoked **independently**:
 
 ## Graceful Degradation
 
-- If adoption files are missing, skip design and infrastructure categories — report only code-level debt (code smells, duplication, test gaps, documentation).
+See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → fall back to built-in heuristics: complexity thresholds, naming patterns, test file presence; adoption file missing → skip the categories that depend on it) for the standard scenarios. Additional cases:
+
 - If [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) is not found, skip infrastructure dependency checks.
 - If [architecture.md](../../../.pair/adoption/tech/architecture.md) is not found, skip design debt detection for architectural violations.
-- If guidelines are not found, use built-in heuristics for detection (complexity thresholds, naming patterns, test file presence).
 
 ## Notes
 
-- **Idempotent**: re-invocation on an already-analyzed codebase confirms the existing analysis. Re-analysis only on explicit developer request.
+- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: existing analysis for the codebase/PR (Step 1, Path B).
 - Prioritization formula `Impact × (6 - Effort)` favors quick wins: high-impact items with low effort get the highest scores.
 - Debt is contextual — the same pattern may be acceptable in a prototype but unacceptable in production code. Severity assessment considers the project's maturity and risk tolerance.

.claude/skills/pair-capability-assess-ai/SKILL.md

@@ -30,25 +30,11 @@ The rendered adoption content is destined for this section — the caller writes
 
 ### Step 1: Resolution Cascade
 
-#### Path A — Argument Override
+Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify).
 
-1. **Check**: Is `$choice` provided?
-2. **Skip**: If not provided, go to Path B.
-3. **Act**: Confirm the choice. Check for conflicts with existing adoption.
-4. **Verify**: Developer confirms. Proceed to Step 3.
-
-#### Path B — Adoption Exists
-
-1. **Check**: Does [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) exist and contain a populated **AI** section?
-2. **Skip**: If no AI section or empty, go to Path C.
-3. **Act**: Read current AI adoption. Confirm it's valid.
-4. **Check**: Does a corresponding decision record exist?
-5. **Act**: If decision record missing, report it as a gap in the output — this skill writes nothing; the caller persists a backfill via `/pair-capability-record-decision`.
-6. **Verify**: Done — exit skill.
-
-#### Path C — Full Assessment
-
-1. **Act**: Proceed to Step 2.
+- **Path A delta**: override argument is `$choice`. On confirm, proceed to Step 3.
+- **Path B delta**: adoption check is [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) — populated **AI** section. If a corresponding decision record is missing, report the gap (this skill still writes nothing; the caller persists a backfill via `/pair-capability-record-decision`).
+- **Path C delta**: proceed to Step 2.
 
 ### Step 2: Read Guidelines
 
@@ -106,10 +92,12 @@ The rendered adoption content is destined for this section — the caller writes
    - `target`: [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) (AI section)
    - `decision-metadata`: `$type: non-architectural`, `$topic: ai-development-tools`, `$summary: "[Primary tool] adopted as AI development assistant with [maturity level] target"`
    - plus the human-facing report (see Output Format)
-2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/pair-capability-record-decision(content, target, decision-metadata)`, never by this skill.
+2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (never persisted by this skill).
 
 ## Output Format
 
+Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape).
+
 ```text
 ASSESSMENT COMPLETE (output-only — no files written):
 ├── Domain:    AI Development
@@ -123,15 +111,14 @@ ASSESSMENT COMPLETE (output-only — no files written):
 
 ## Composition Interface
 
+See [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape.
+
 When composed by `/pair-process-bootstrap`:
 
 - **Input**: `/pair-process-bootstrap` invokes during Phase 2.
-- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing.
-- **Persistence**: `/pair-process-bootstrap` accepts the proposal and composes `/pair-capability-record-decision(content, target, decision-metadata)` to write the AI section and record the ADL.
-
-When invoked **independently**:
+- **Persistence**: `/pair-process-bootstrap` composes `/pair-capability-record-decision` to write the AI section and record the ADL.
 
-- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits.
+When invoked **independently**: the human (or agent) persists the proposal by composing `/pair-capability-record-decision`, then commits.
 
 ## Edge Cases
 
@@ -142,9 +129,7 @@ When invoked **independently**:
 
 ## Graceful Degradation
 
-- If AI development guidelines not found, use minimal assessment: ask developer for AI tool preferences.
-- If the caller cannot persist (e.g. `/pair-capability-record-decision` not installed), the proposal stands as a report — adoption stays unchanged.
-- If tech-stack.md doesn't exist, the assessment still runs — the caller creates the file on persist via `/pair-capability-record-decision`.
+See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for AI tool preferences directly) and [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) (persistence unavailable → proposal stands as a report) for the standard scenarios. No additional cases.
 
 ## Notes
 

.claude/skills/pair-capability-assess-architecture/SKILL.md

@@ -30,36 +30,11 @@ The rendered adoption content is destined for this file — the caller writes it
 
 ### Step 1: Resolution Cascade
 
-#### Path A — Argument Override
+Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify).
 
-1. **Check**: Is `$choice` provided?
-2. **Skip**: If not provided, go to Path B.
-3. **Act**: Confirm the choice with the developer:
-
-   > Architecture override: **$choice**.
-   > This will be proposed without full assessment.
-   > Confirm?
-
-4. **Check**: Does an adoption file already exist with a different pattern?
-   - If yes, warn: "Current adoption is **[existing]**. Override to **$choice**?"
-5. **Verify**: Developer confirms. Proceed to Step 2.
-
-#### Path B — Adoption Exists
-
-1. **Check**: Does [adoption/tech/architecture.md](../../../.pair/adoption/tech/architecture.md) exist and is it populated (not template)?
-2. **Skip**: If not populated or missing, go to Path C.
-3. **Act**: Read current adoption. Present:
-
-   > Architecture already adopted: **[pattern name]**.
-   > Adoption file is current and valid.
-
-4. **Check**: Does a corresponding decision record exist? (Scan [adoption/tech/adr/](../../../.pair/adoption/tech/adr) for `*architecture*` files.)
-5. **Act**: If decision record missing, report it as a gap in the output — this skill writes nothing; the caller persists a backfill via `/pair-capability-record-decision`.
-6. **Verify**: Adoption and decision record consistent. Done — exit skill.
-
-#### Path C — Full Assessment
-
-1. **Act**: Proceed to Step 2 (full assessment mode).
+- **Path A delta**: override argument is `$choice`. Confirmation prompt: "Architecture override: **$choice**. This will be proposed without full assessment. Confirm?" — also warn if adoption already holds a different pattern. On confirm, proceed to Step 2.
+- **Path B delta**: adoption check is [adoption/tech/architecture.md](../../../.pair/adoption/tech/architecture.md), populated (not template). Decision-record check scans [adoption/tech/adr/](../../../.pair/adoption/tech/adr) for `*architecture*` files; if missing, report the gap (this skill still writes nothing; the caller persists a backfill via `/pair-capability-record-decision`).
+- **Path C delta**: proceed to Step 2 (full assessment mode).
 
 ### Step 2: Read Guidelines
 
@@ -107,10 +82,12 @@ The rendered adoption content is destined for this file — the caller writes it
    - `target`: [adoption/tech/architecture.md](../../../.pair/adoption/tech/architecture.md) (owned section)
    - `decision-metadata`: `$type: architectural`, `$topic: architecture-pattern`, `$summary: "[Pattern] adopted as system architecture"`
    - plus the human-facing report (see Output Format)
-2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/pair-capability-record-decision(content, target, decision-metadata)`, never by this skill.
+2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (never persisted by this skill).
 
 ## Output Format
 
+Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape).
+
 ```text
 ASSESSMENT COMPLETE (output-only — no files written):
 ├── Domain:    Architecture
@@ -124,15 +101,14 @@ ASSESSMENT COMPLETE (output-only — no files written):
 
 ## Composition Interface
 
+See [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape.
+
 When composed by `/pair-process-bootstrap`:
 
 - **Input**: `/pair-process-bootstrap` invokes `/pair-capability-assess-architecture` during Phase 2 (checklist completion). May pass `$choice` if developer pre-selected.
-- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing.
-- **Persistence**: `/pair-process-bootstrap` accepts the proposal and composes `/pair-capability-record-decision(content, target, decision-metadata)` to write the adoption file and record the ADR, then includes those changes in the next commit.
-
-When invoked **independently**:
+- **Persistence**: `/pair-process-bootstrap` composes `/pair-capability-record-decision` to write the adoption file and record the ADR, then includes those changes in the next commit.
 
-- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits.
+When invoked **independently**: the human (or agent) persists the proposal by composing `/pair-capability-record-decision`, then commits.
 
 ## Edge Cases
 
@@ -143,9 +119,7 @@ When invoked **independently**:
 
 ## Graceful Degradation
 
-- If architecture guidelines are not found, use minimal decision framework: ask developer to choose between Modular Monolith, Hexagonal, and Microservices based on team size and scale needs.
-- If the caller cannot persist (e.g. `/pair-capability-record-decision` not installed), the proposal stands as a report — adoption stays unchanged until an explicit decision is recorded.
-- If adoption files are missing, the assessment still runs and produces its proposal (nothing to write anyway).
+See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal decision framework: ask developer to choose between Modular Monolith, Hexagonal, and Microservices based on team size/scale) and [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) (persistence unavailable → proposal stands as a report) for the standard scenarios. No additional cases.
 
 ## Notes