diff --git a/.claude/skills/pair-capability-analyze-code-quality/SKILL.md b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md index ff058b78..e0e8aadc 100644 --- a/.claude/skills/pair-capability-analyze-code-quality/SKILL.md +++ b/.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,7 +141,8 @@ 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." @@ -160,7 +150,7 @@ When invoked **independently**: ## 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. diff --git a/.claude/skills/pair-capability-analyze-debt/SKILL.md b/.claude/skills/pair-capability-analyze-debt/SKILL.md index 60efa5e5..5931d8f0 100644 --- a/.claude/skills/pair-capability-analyze-debt/SKILL.md +++ b/.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. diff --git a/.claude/skills/pair-capability-assess-ai/SKILL.md b/.claude/skills/pair-capability-assess-ai/SKILL.md index 233c543b..5a850fcc 100644 --- a/.claude/skills/pair-capability-assess-ai/SKILL.md +++ b/.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 diff --git a/.claude/skills/pair-capability-assess-architecture/SKILL.md b/.claude/skills/pair-capability-assess-architecture/SKILL.md index e2931782..cca703a5 100644 --- a/.claude/skills/pair-capability-assess-architecture/SKILL.md +++ b/.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 diff --git a/.claude/skills/pair-capability-assess-infrastructure/SKILL.md b/.claude/skills/pair-capability-assess-infrastructure/SKILL.md index 2a8b3381..d95bfb86 100644 --- a/.claude/skills/pair-capability-assess-infrastructure/SKILL.md +++ b/.claude/skills/pair-capability-assess-infrastructure/SKILL.md @@ -30,25 +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. Check for conflicts with existing adoption. -4. **Verify**: Developer confirms. Proceed to Step 3. - -#### Path B — Adoption Exists - -1. **Check**: Does [adoption/tech/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) exist and is it populated? -2. **Skip**: If not populated or missing, go to Path C. -3. **Act**: Read current 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/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md), populated. 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 @@ -96,10 +82,12 @@ The rendered adoption content is destined for this file — the caller writes it - `target`: [adoption/tech/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) (core sections) - `decision-metadata`: `$type: architectural` (infrastructure decisions affect system structure), `$topic: infrastructure-strategy`, `$summary: "[Summary of key infrastructure choices]"` - 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: Infrastructure @@ -113,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 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 infrastructure.md and record the ADR. - -When invoked **independently**: +- **Persistence**: `/pair-process-bootstrap` composes `/pair-capability-record-decision` to write infrastructure.md and record the ADR. -- 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 @@ -131,9 +118,7 @@ When invoked **independently**: ## Graceful Degradation -- If infrastructure guidelines not found, use minimal assessment: ask developer for CI/CD and deployment preferences. -- If the caller cannot persist (e.g. `/pair-capability-record-decision` not installed), the proposal stands as a report — adoption stays unchanged. -- If adoption files are missing, 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 CI/CD and deployment 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 diff --git a/.claude/skills/pair-capability-assess-methodology/SKILL.md b/.claude/skills/pair-capability-assess-methodology/SKILL.md index f46d2dbf..088b2ce4 100644 --- a/.claude/skills/pair-capability-assess-methodology/SKILL.md +++ b/.claude/skills/pair-capability-assess-methodology/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/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) exist and contain a methodology reference (e.g. "Kanban", "Scrum", or similar)? -2. **Skip**: If no methodology defined, go to Path C. -3. **Act**: Read current 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/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) containing a methodology reference (e.g. "Kanban", "Scrum"). 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 @@ -101,10 +87,12 @@ The rendered adoption content is destined for this section — the caller writes - `target`: [adoption/tech/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) (methodology section) - `decision-metadata`: `$type: non-architectural`, `$topic: methodology-choice`, `$summary: "[Methodology] adopted for development workflow"` - 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: Methodology @@ -118,15 +106,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 methodology section and record the ADL. - -When invoked **independently**: +- **Persistence**: `/pair-process-bootstrap` composes `/pair-capability-record-decision` to write the methodology 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 @@ -136,9 +123,7 @@ When invoked **independently**: ## Graceful Degradation -- If methodology guidelines not found, use minimal assessment: ask developer for methodology preference based on team size and requirements stability. -- If the caller cannot persist (e.g. `/pair-capability-record-decision` not installed), the proposal stands as a report — adoption stays unchanged. -- If way-of-working.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 methodology preference based on team size/requirements stability) 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 diff --git a/.claude/skills/pair-capability-assess-observability/SKILL.md b/.claude/skills/pair-capability-assess-observability/SKILL.md index 517fd590..2f901c75 100644 --- a/.claude/skills/pair-capability-assess-observability/SKILL.md +++ b/.claude/skills/pair-capability-assess-observability/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/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) exist and contain a populated **observability** section? -2. **Skip**: If no observability section or empty, go to Path C. -3. **Act**: Read current observability 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/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) — populated **observability** 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 @@ -99,10 +85,12 @@ The rendered adoption content is destined for this section — the caller writes - `target`: [adoption/tech/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) (observability section) - `decision-metadata`: `$type: non-architectural` (observability tooling is typically a tool choice), `$topic: observability-strategy`, `$summary: "[Platform] adopted for observability with [logging approach]"` - 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: Observability @@ -116,15 +104,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, after /pair-capability-assess-infrastructure. -- **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 observability section and record the ADL. - -When invoked **independently**: +- **Persistence**: `/pair-process-bootstrap` composes `/pair-capability-record-decision` to write the observability 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 @@ -134,9 +121,7 @@ When invoked **independently**: ## Graceful Degradation -- If observability guidelines not found, use minimal assessment: ask developer for platform preference. -- If the caller cannot persist (e.g. `/pair-capability-record-decision` not installed), the proposal stands as a report — adoption stays unchanged. -- If infrastructure.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 platform preference 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 diff --git a/.claude/skills/pair-capability-assess-pm/SKILL.md b/.claude/skills/pair-capability-assess-pm/SKILL.md index a368f8d9..1c7177bb 100644 --- a/.claude/skills/pair-capability-assess-pm/SKILL.md +++ b/.claude/skills/pair-capability-assess-pm/SKILL.md @@ -34,25 +34,11 @@ The rendered adoption content is destined for this section — the caller (or `/ ### 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/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) contain a PM tool configuration? -2. **Skip**: If no PM tool defined, go to Path C. -3. **Act**: Read current PM 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 a PM tool configuration in [adoption/tech/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md). 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 @@ -105,10 +91,12 @@ The rendered adoption content is destined for this section — the caller (or `/ - `target`: [adoption/tech/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) (PM tool section) - `decision-metadata`: `$type: non-architectural`, `$topic: pm-tool-choice`, `$summary: "[Tool] adopted for project management"` - plus the human-facing report (see Output Format) -3. **Verify**: Proposal emitted. Persistence is performed by the caller via `/pair-capability-record-decision(content, target, decision-metadata)`, never by this skill. +3. **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) (with a `Delegated` status for the /pair-capability-setup-pm handoff — a legitimate per-skill variant, see that file). + ```text ASSESSMENT COMPLETE (output-only for adoption — no files written by this skill): ├── Domain: Project Management @@ -122,15 +110,14 @@ ASSESSMENT COMPLETE (output-only for adoption — no files written by this skill ## 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 (checklist completion). May pass `$choice`. -- **Output**: If `/pair-capability-setup-pm` was composed, returns its output. Otherwise returns `{ content, target, decision-metadata }` plus the report — writes nothing. -- **Persistence**: when not delegated, `/pair-process-bootstrap` accepts the proposal and composes `/pair-capability-record-decision(content, target, decision-metadata)`. - -When invoked **independently**: +- **Persistence**: if `/pair-capability-setup-pm` was composed, it already persisted — otherwise `/pair-process-bootstrap` composes `/pair-capability-record-decision`. -- Full interactive flow. If `/pair-capability-setup-pm` is present it persists; otherwise the human (or agent) persists the proposal by composing `/pair-capability-record-decision`, then commits. +When invoked **independently**: if `/pair-capability-setup-pm` is present it persists; otherwise the human (or agent) persists the proposal by composing `/pair-capability-record-decision`, then commits. ## Edge Cases @@ -140,9 +127,7 @@ When invoked **independently**: ## Graceful Degradation -- If PM tool guidelines not found, use minimal assessment: ask developer for tool preference. -- If `/pair-capability-setup-pm` not installed, emit the proposal for the caller to persist via `/pair-capability-record-decision` (no tool-specific configuration). -- If the caller cannot persist (e.g. `/pair-capability-record-decision` not installed), the proposal stands as a report — adoption stays unchanged. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for tool preference directly; optional skill `/pair-capability-setup-pm` not installed → emit the proposal for the caller to persist via `/pair-capability-record-decision`, no tool-specific configuration) 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 diff --git a/.claude/skills/pair-capability-assess-stack/SKILL.md b/.claude/skills/pair-capability-assess-stack/SKILL.md index a9e2ea9a..a946c3ec 100644 --- a/.claude/skills/pair-capability-assess-stack/SKILL.md +++ b/.claude/skills/pair-capability-assess-stack/SKILL.md @@ -59,41 +59,11 @@ Detect and evaluate unlisted dependencies. Used when `/pair-process-review` find ### Step 1: Resolution Cascade -#### Path A — Argument Override (implementation or bootstrap with $choice) +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** (implementation mode): Validate compatibility: - - Parse `$choice` as `name@version`. - - Check existing [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) for conflicts: - - Version incompatibility (e.g. library needs Node 20, stack has Node 18) - - Duplicate entry (same library already listed) - - Category conflict (e.g. two ORMs) - - If conflict detected, warn developer: - - > **Compatibility issue**: `$choice` conflicts with existing stack. - > - Conflict: [description] - > - Options: (a) resolve conflict and proceed, (b) reject addition - -4. **Act** (bootstrap mode with choice): Confirm the choice and proceed to Step 3. -5. **Verify**: Choice validated. Proceed to Step 3. - -#### Path B — Adoption Exists - -1. **Check**: Does [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) exist with populated core sections? -2. **Skip**: If not populated or missing, go to Path C. -3. **Act**: Read current adoption. Present summary: - - > Tech stack already adopted. Core sections populated. - > [Summary of key technologies with versions] - -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**: Adoption and decision record consistent. Done — exit skill. - -#### Path C — Full Assessment (bootstrap mode) - -1. **Act**: Proceed to Step 2 (full assessment). +- **Path A delta** (implementation or bootstrap with `$choice`): parse `$choice` as `name@version`; in implementation mode, validate against [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) for version incompatibility, duplicate entry, or category conflict — warn and offer resolve-or-reject if found. In bootstrap mode with a choice, just confirm. Proceed to Step 3. +- **Path B delta**: adoption check is [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) with populated core sections. 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** (bootstrap mode): proceed to Step 2 (full assessment). ### Step 2: Read Guidelines (bootstrap mode only) @@ -183,7 +153,7 @@ Detect and evaluate unlisted dependencies. Used when `/pair-process-review` find - **Implementation**: `$type: non-architectural`, `$topic: stack-add-[name]`, `$summary: "[name]@[version] added to tech stack — [rationale]"` - **Review approve**: `$type: non-architectural`, `$topic: stack-approve-[name]`, `$summary: "[name]@[version] approved during review — added to tech stack"` - plus the human-facing report (see Output Format), and the validation result (approved/rejected) for implementation/review modes -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). ## Version Tracking Policy @@ -205,6 +175,8 @@ Detect and evaluate unlisted dependencies. Used when `/pair-process-review` find ## Output Format +Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape) (with an added `Mode` line — a legitimate per-skill variant, see that file, since this skill spans the whole project lifecycle). + ```text ASSESSMENT COMPLETE (output-only — no files written): ├── Domain: Tech Stack @@ -219,27 +191,26 @@ 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-stack` during Phase 2 with `$mode: bootstrap`. May pass `$choice` for pre-selected stack. -- **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)`, then includes those changes in the next commit. +- **Persistence**: `/pair-process-bootstrap` composes `/pair-capability-record-decision`, then includes those changes in the next commit. When composed by `/pair-process-implement`: - **Input**: `/pair-process-implement` detects new import/dependency → invokes `/pair-capability-assess-stack` with `$choice: [name@version]`, `$mode: implementation`. -- **Output**: Returns the validation result (approved/rejected) plus, when approved, `{ content, target, decision-metadata }`. +- **Output**: Returns the validation result (approved/rejected) plus, when approved, the proposal. - **Persistence**: on approval, `/pair-process-implement` persists the entry via `/pair-capability-record-decision`. If rejected (incompatible) → `/pair-process-implement` HALTs. When composed by `/pair-process-review`: - **Input**: `/pair-process-review` detects unlisted dependency → invokes `/pair-capability-assess-stack` with `$choice: [name@version]`, `$mode: review`. -- **Output**: Returns the developer decision (approve/reject) plus, when approved, `{ content, target, decision-metadata }`. +- **Output**: Returns the developer decision (approve/reject) plus, when approved, the proposal. - **Persistence**: on approval, `/pair-process-review` persists via `/pair-capability-record-decision`. If rejected → `/pair-process-review` includes as CHANGES-REQUESTED finding. -When invoked **independently**: - -- Full interactive flow. Mode auto-detected. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits. +When invoked **independently**: mode auto-detected. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits. ## Edge Cases @@ -252,10 +223,10 @@ When invoked **independently**: ## Graceful Degradation -- If technology guidelines are not found, use minimal assessment: ask developer for stack choices directly. -- If the caller cannot persist (e.g. `/pair-capability-record-decision` not installed), the proposal stands as a report — adoption stays unchanged. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for stack choices directly; adoption file missing in bootstrap mode → the skill still runs, caller creates it on persist) and [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) (persistence unavailable → proposal stands as a report) for the standard scenarios. Additional cases: + - If architecture.md doesn't exist, warn: "No architecture adopted — stack compatibility cannot be verified against architecture." -- If tech-stack.md doesn't exist (bootstrap mode), the caller creates it on persist. If implementation/review mode, HALT: "No tech stack defined — run /pair-capability-assess-stack in bootstrap mode first." +- If tech-stack.md doesn't exist in implementation/review mode (as opposed to bootstrap, covered above), HALT: "No tech stack defined — run /pair-capability-assess-stack in bootstrap mode first." ## Notes diff --git a/.claude/skills/pair-capability-assess-testing/SKILL.md b/.claude/skills/pair-capability-assess-testing/SKILL.md index 5a619bdd..c3b77cf2 100644 --- a/.claude/skills/pair-capability-assess-testing/SKILL.md +++ b/.claude/skills/pair-capability-assess-testing/SKILL.md @@ -30,40 +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 with the developer: - - > Testing framework override: **$choice**. - > This will be proposed without full assessment. - > Confirm? - -4. **Check**: Does [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) already have a testing section with a different framework? - - If yes, warn: "Current testing framework is **[existing]**. Override to **$choice**?" -5. **Verify**: Developer confirms. Proceed to Step 2. - -#### Path B — Adoption Exists - -1. **Check**: Does [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) exist and contain a populated **Testing** section? -2. **Skip**: If no testing section or section is empty/template, go to Path C. -3. **Act**: Read current testing adoption. Present: - - > Testing strategy already adopted: - > - Framework: **[name vX.Y]** - > - Coverage tool: **[name vX.Y]** - > - Additional tools: **[list]** - > - > Adoption is current and valid. - -4. **Check**: Does a corresponding decision record exist? (Scan [adoption/decision-log/](../../../.pair/adoption/decision-log) or [adoption/tech/adr/](../../../.pair/adoption/tech/adr) for `*testing*` 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: "Testing framework override: **$choice**. This will be proposed without full assessment. Confirm?" — also warn if tech-stack.md already has a testing section with a different framework. On confirm, proceed to Step 2. +- **Path B delta**: adoption check is [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) — populated **Testing** section. Decision-record check scans [adoption/decision-log/](../../../.pair/adoption/decision-log) or [adoption/tech/adr/](../../../.pair/adoption/tech/adr) for `*testing*` 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 @@ -117,10 +88,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) (Testing section) - `decision-metadata`: `$type: non-architectural` (testing framework is a tooling choice), `$topic: testing-strategy`, `$summary: "[Framework] vX.Y adopted as testing framework with [coverage target]% coverage"` - 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: Testing @@ -134,15 +107,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-testing` during Phase 2. 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 Testing section and record the ADL, then includes those changes in the next commit. - -When invoked **independently**: +- **Persistence**: `/pair-process-bootstrap` composes `/pair-capability-record-decision` to write the Testing section and record the ADL, 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 @@ -154,9 +126,7 @@ When invoked **independently**: ## Graceful Degradation -- If testing guidelines are not found, use minimal assessment: ask developer for framework preference based on language. -- 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 and produces its proposal — 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 framework preference based on language) 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 diff --git a/.claude/skills/pair-capability-checkpoint/SKILL.md b/.claude/skills/pair-capability-checkpoint/SKILL.md index 0e570da6..14d26e49 100644 --- a/.claude/skills/pair-capability-checkpoint/SKILL.md +++ b/.claude/skills/pair-capability-checkpoint/SKILL.md @@ -136,15 +136,16 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → use a minimal structure directly; PM tool not accessible during state reconstruction, Step 3 → ask the developer to confirm tasks done/pending directly) for the standard scenarios. Additional cases: + - If the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md) is not found, use the minimal five-section structure directly: Story, Branch, Tasks Done, Key Decisions, Remaining Todos. - If `.pair/working/` does not exist yet, create it (and `checkpoints/` under it) on first write. - If git is not available or the branch cannot be determined, mark the Branch section `[unknown — needs confirmation]` rather than guessing. -- If the PM tool is not accessible during state reconstruction (Step 3), ask the developer to confirm tasks done/pending directly. ## Notes - This skill **writes at most one file** — `.pair/working/checkpoints/.md` — and only in write mode with `$persist=true` (default). -- **Idempotent**: re-invoking write mode updates the same file in place; it never duplicates. Re-invoking resume mode is read-only and safe to repeat. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: write mode updates the same file in place (never duplicates); resume mode is read-only and safe to repeat. - `.pair/working/` holds operational, per-project runtime state — never touched by install or update (D14). It is not part of the distributed KB defaults. - Checkpoints complement, not replace, git/PM-tool state. Even when state is reliably reconstructible from git and the PM tool (as `/pair-process-implement` does today), a checkpoint adds an explicit, fast-to-read summary — most valuable across context resets and subagent handoffs, where reconstruction from scratch is expensive or impossible. - The write-free (`$persist=false`) option serves composers that own their own persistence (e.g., embedding the handoff directly into a PR body) rather than writing a separate file. diff --git a/.claude/skills/pair-capability-design-manual-tests/SKILL.md b/.claude/skills/pair-capability-design-manual-tests/SKILL.md index f41d1b6c..58f8aee3 100644 --- a/.claude/skills/pair-capability-design-manual-tests/SKILL.md +++ b/.claude/skills/pair-capability-design-manual-tests/SKILL.md @@ -165,6 +165,6 @@ When invoked **independently**: - This skill **generates test definitions** — it does not execute tests or modify application code. - Test case IDs are stable across regenerations if the same surfaces are discovered. -- The skill is idempotent: re-running on an existing suite offers regenerate/extend/abort. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-running on an existing suite offers regenerate/extend/abort. - Generated test cases are version-agnostic by design — they work across releases without modification. - Suite maintenance (adding tests for new features) should re-invoke this skill with `extend` mode. diff --git a/.claude/skills/pair-capability-estimate/SKILL.md b/.claude/skills/pair-capability-estimate/SKILL.md index 2c66d7e2..3f4f4362 100644 --- a/.claude/skills/pair-capability-estimate/SKILL.md +++ b/.claude/skills/pair-capability-estimate/SKILL.md @@ -20,7 +20,7 @@ Apply the adopted estimation methodology to size a refined user story. Reads the ### Step 1: Load Story -1. **Check**: Read the story from the PM tool (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)). +1. **Check**: Read the story from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md). 2. **Verify**: Story exists and has acceptance criteria. If not refined → **HALT**: "Story must be refined before estimation." ### Step 2: Check Existing Estimate @@ -108,14 +108,14 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → fall back to developer judgment; PM tool not accessible → ask the developer to record manually) for the standard scenarios. Additional cases: + - If [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) does not specify an estimation methodology, use the Decision Matrix from the estimation guidelines to recommend one. -- If estimation guidelines are not found, fall back to developer judgment: ask the developer to provide an estimate directly and record it. -- If the PM tool is not accessible, present the estimate and ask the developer to record it manually. - If the story has no acceptance criteria, warn: "Story lacks AC — estimation may be inaccurate. Consider refining first." ## Notes - This skill **modifies the PM tool** — it writes the estimate to the story issue. -- **Idempotent**: re-invocation on an already-estimated story confirms the existing estimate without re-doing the analysis. Re-estimation only happens on explicit developer request. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: an already-estimated story is confirmed without re-doing the analysis; re-estimation only on explicit developer request. - The estimation method should be consistent within a project. If the team switches methods, record the decision via `/pair-capability-record-decision`. - Estimation is a collaborative activity — the skill proposes, the developer decides. The skill never overrides developer judgment. diff --git a/.claude/skills/pair-capability-execute-manual-tests/SKILL.md b/.claude/skills/pair-capability-execute-manual-tests/SKILL.md index bf3b664f..cf070bd2 100644 --- a/.claude/skills/pair-capability-execute-manual-tests/SKILL.md +++ b/.claude/skills/pair-capability-execute-manual-tests/SKILL.md @@ -162,11 +162,13 @@ To maximize reliability when executed by AI agents: - **Version from artifact**: extract from the artifact itself, never from source code. - **Isolated filesystem**: `$WORKDIR` must be outside the repo to avoid workspace interference. - **Clean npm environment**: use `--no-workspaces`, ensure no `.npmrc` inheritance from parent dirs. -- **Idempotent re-run**: re-executing produces the same result without manual cleanup. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-executing produces the same result without manual cleanup. ## Graceful Degradation -- **No test suite found**: HALT with guidance to run `/pair-capability-design-manual-tests` first. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → use a minimal structure directly) for the standard scenarios. Additional cases: + +- **No test suite found**: HALT with guidance to run `/pair-capability-design-manual-tests` first (a required dependency, not optional). - **`agent-browser` not available**: Fall back to Playwright MCP. If Playwright MCP also unavailable, fall back to WebFetch/curl for HTTP checks. Mark interactive tests (search, responsive) as BLOCKED. - **No internet**: Skip tests requiring network (website, registry, auto-download). Mark as BLOCKED with reason. - **Suite-specific variable not resolvable**: Mark dependent tests as BLOCKED with the resolution hint from the suite README. diff --git a/.claude/skills/pair-capability-grill/SKILL.md b/.claude/skills/pair-capability-grill/SKILL.md index 3822e1b0..aa075398 100644 --- a/.claude/skills/pair-capability-grill/SKILL.md +++ b/.claude/skills/pair-capability-grill/SKILL.md @@ -205,9 +205,10 @@ AI: GRILL SESSION COMPLETE — Mode: sync · Coverage: 6/6 · returns alignment ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (composing skill not installed → this skill still runs standalone) for the standard scenarios. Additional cases: + - If KB/codebase exploration is unavailable (no repo access), skip Step 1 (nothing marked explored), ask every aspect/topic question directly, and note in the synthesis that explore-first was skipped. - If `.pair/working/` cannot be created or written, present the handoff content inline in conversation and tell the human to save it manually. -- If the composing skill (`/pair-process-brainstorm`, `/pair-process-refine-story`) is not installed, grill still runs standalone — it has no required composed skills. ## Notes diff --git a/.claude/skills/pair-capability-manage-flags/SKILL.md b/.claude/skills/pair-capability-manage-flags/SKILL.md index 5433e4a8..11e03301 100644 --- a/.claude/skills/pair-capability-manage-flags/SKILL.md +++ b/.claude/skills/pair-capability-manage-flags/SKILL.md @@ -124,7 +124,8 @@ When invoked **independently**: ## Graceful Degradation -- If [feature-flags.md](../../../.pair/knowledge/guidelines/technical-standards/feature-flags.md) is not found, provide framework-agnostic patterns: simple boolean flags with environment variables. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → fall back to framework-agnostic patterns: simple boolean flags with environment variables) for the standard scenarios. Additional cases: + - If no feature flag tool is configured, use code-level flags (constants, config files) rather than a flag service. - If no existing flags are found in the codebase, report empty inventory and offer to create the first flag. - If cleanup would break active code paths, warn and require explicit developer confirmation. @@ -132,7 +133,7 @@ When invoked **independently**: ## Notes - This skill **modifies files** — it creates, activates, deactivates, and removes feature flag code and configuration. -- **Idempotent**: invoking `create` on an existing flag shows its current state instead of re-creating. Invoking `activate` on an active flag confirms the state. Invoking `cleanup` always requires explicit confirmation. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: `create` on an existing flag shows its current state instead of re-creating; `activate` on an active flag confirms the state; `cleanup` always requires explicit confirmation. - **Stale flag detection**: flags inactive for more than 30 days are flagged as stale. Cleanup is recommended but not forced. - Flag naming conventions should follow the project's adopted coding standards (e.g., `SCREAMING_SNAKE_CASE` for env vars, `camelCase` for code constants). - Cleanup is the most critical lifecycle phase — leftover flags create technical debt. The `status` action helps identify cleanup candidates. diff --git a/.claude/skills/pair-capability-map-contexts/SKILL.md b/.claude/skills/pair-capability-map-contexts/SKILL.md index 7cb10de5..994d7fa8 100644 --- a/.claude/skills/pair-capability-map-contexts/SKILL.md +++ b/.claude/skills/pair-capability-map-contexts/SKILL.md @@ -153,6 +153,8 @@ CONTEXT PLACEMENT COMPLETE: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (adoption files missing → warn, proceed with what's available rather than halting) for the standard scenarios. Additional cases: + - If architecture or tech-stack adoption files are missing, warn and infer boundaries from subdomains alone. - If subdomains have no `Volatility` field yet, treat volatility as unknown/Medium for the assessment and note it as provisional. - If neither a subdomain nor a bounded-context catalog exists, use the system-areas fallback (Step 2b) rather than halting. @@ -162,7 +164,7 @@ CONTEXT PLACEMENT COMPLETE: ## Notes - This skill **creates/updates adoption files** — not PM tool issues. Bounded contexts are design artifacts. -- Idempotent: re-invocation detects existing files by filename; only entries inside `$scope` are evaluated for changes. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing files by filename; only entries inside `$scope` are evaluated for changes. - The 3-dimension relationship assessment (strength, distance, volatility) is the input to the coupling-balance guideline — see `.pair/knowledge/guidelines/architecture/design-patterns/coupling-balance.md` (introduced by #209); until that guideline lands, apply the heuristics in Step 3 directly. - Contract-coupled (`contract` strength) relationships are annotated "contract tests expected" — `/pair-capability-design-manual-tests` and story-level validation strategies should pick up the contract/boundary test category for that relationship. - Migration: this skill was reclassified from a process skill (`pair-process-map-contexts`) to a capability (`pair-capability-map-contexts`) — see [skills-guide.md](../../../.pair/knowledge/skills-guide.md#migration-notes) for the rename and new invocation paths. diff --git a/.claude/skills/pair-capability-map-subdomains/SKILL.md b/.claude/skills/pair-capability-map-subdomains/SKILL.md index 9c6f17e8..ca7ae6a8 100644 --- a/.claude/skills/pair-capability-map-subdomains/SKILL.md +++ b/.claude/skills/pair-capability-map-subdomains/SKILL.md @@ -139,6 +139,8 @@ SUBDOMAIN PLACEMENT COMPLETE: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (adoption/context inputs missing → warn, proceed with what's available rather than halting) for the standard scenarios. Additional cases: + - If initiatives are not available but PRD is, proceed with PRD-only analysis and warn. - If neither PRD nor initiatives nor an existing catalog are available, use the system-areas fallback (Step 2b) rather than halting. - If the adoption directory doesn't exist, create it. @@ -147,7 +149,7 @@ SUBDOMAIN PLACEMENT COMPLETE: ## Notes - This skill **creates/updates adoption files** — not PM tool issues. Subdomains are design artifacts. -- Idempotent: re-invocation detects existing files by filename; only entries inside `$scope` are evaluated for changes. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing files by filename; only entries inside `$scope` are evaluated for changes. - Volatility is evaluated from the business domain (classification-derived default + human override), never from commit history alone. - DDD classification and Volatility drive downstream assessments — see `/pair-capability-map-contexts` (relationship strength/distance/volatility) and the architecture-quality capability that consumes them. - Migration: this skill was reclassified from a process skill (`pair-process-map-subdomains`) to a capability (`pair-capability-map-subdomains`) — see [skills-guide.md](../../../.pair/knowledge/skills-guide.md#migration-notes) for the rename and new invocation paths. diff --git a/.claude/skills/pair-capability-record-decision/SKILL.md b/.claude/skills/pair-capability-record-decision/SKILL.md index e42e73da..8b16d944 100644 --- a/.claude/skills/pair-capability-record-decision/SKILL.md +++ b/.claude/skills/pair-capability-record-decision/SKILL.md @@ -180,9 +180,11 @@ When invoked **independently**: ## Graceful Degradation -- If [ADR template](../../../.pair/knowledge/guidelines/collaboration/templates/adr-template.md) is not found, use the minimal ADR structure: Status, Date, Context, Decision, Consequences, Adoption Impact. -- If [ADL template](../../../.pair/knowledge/guidelines/collaboration/templates/adl-template.md) is not found, use the minimal ADL structure: Date, Status, Context, Decision, Consequences, Adoption Impact. -- If [DDR template](../../../.pair/knowledge/guidelines/collaboration/templates/ddr-template.md) is not found, use the minimal DDR structure: Status, Date, Context, Decision, Consequences, Context Map Impact. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → use a minimal structure directly) for the standard scenarios. Additional cases (the minimal structure per decision type): + +- ADR template missing → minimal ADR structure: Status, Date, Context, Decision, Consequences, Adoption Impact. +- ADL template missing → minimal ADL structure: Date, Status, Context, Decision, Consequences, Adoption Impact. +- DDR template missing → minimal DDR structure: Status, Date, Context, Decision, Consequences, Context Map Impact. - If adoption directories don't exist, create them and warn: "Created adoption directory — this appears to be a new project." ## Notes diff --git a/.claude/skills/pair-capability-setup-gates/SKILL.md b/.claude/skills/pair-capability-setup-gates/SKILL.md index 68c44463..dbc744d8 100644 --- a/.claude/skills/pair-capability-setup-gates/SKILL.md +++ b/.claude/skills/pair-capability-setup-gates/SKILL.md @@ -154,16 +154,16 @@ When invoked **independently**: ## Graceful Degradation -- If quality-assurance guidelines are not found, propose minimal gates based on detected package.json scripts (test, lint, build). +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → propose minimal gates from what's detectable: detected package.json scripts — test, lint, build) and [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) (`/pair-capability-record-decision` not installed → warn and skip decision recording) for the standard scenarios. Additional cases: + - If tech-stack.md is not found, ask developer for tooling choices to generate appropriate gate commands. -- If `/pair-capability-record-decision` is not installed, warn and skip decision recording. - If no CI/CD platform is detectable, document gate commands for manual execution and skip pipeline file generation. - If the project is not JS/TS, document the shared-config-package pattern generically (see [shared-config-packages.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/shared-config-packages.md) § Non-JS / Polyglot Projects) and skip config-file generation — point to the ecosystem's equivalent shared config package. ## Notes - This skill **modifies files** — it writes to way-of-working.md, creates/updates CI/CD pipeline configuration, and provisions shared lint/format config packages + hook manager files (`.husky/` by default). -- **Idempotent**: re-invocation on an already-configured project confirms the existing configuration, including provisioned shared configs and hooks; update only on explicit developer request. Conflicting local config → ask before overwriting, never silently. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: an already-configured project (incl. provisioned shared configs and hooks) is confirmed; update only on explicit developer request. Conflicting local config → ask before overwriting, never silently. - Gate commands must be executable in the project's development environment. Verify commands exist before writing. - Custom Gate Registry format follows the table schema from [quality-gates.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-standards/quality-gates.md): Order, Gate, Command, Scope Key, Required, Description. - **Hook manager default**: husky (decision D21/Q11). An override recorded in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) wins — this skill reads it before provisioning. diff --git a/.claude/skills/pair-capability-setup-pm/SKILL.md b/.claude/skills/pair-capability-setup-pm/SKILL.md index 40b4343f..6ed86c81 100644 --- a/.claude/skills/pair-capability-setup-pm/SKILL.md +++ b/.claude/skills/pair-capability-setup-pm/SKILL.md @@ -138,9 +138,11 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (adoption file missing → the skill still runs, creates it) for the standard scenarios. **This skill is the documented exception to the generic [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md)**: it writes `way-of-working.md` itself in Step 4, before composing `/pair-capability-record-decision` in Step 5 — so a missing `/pair-capability-record-decision` does not mean "nothing persisted," only that the ADL entry is skipped. Additional cases: + - If [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) doesn't exist, create it with PM section as initial content. Warn: "Created way-of-working.md — this appears to be a new project." - If implementation guide not found for selected tool, HALT with contribution instructions (Step 2.4). -- If `/pair-capability-record-decision` is not installed, warn and skip ADL recording: "Decision not recorded — /pair-capability-record-decision not installed. Please manually document the PM tool choice." +- If `/pair-capability-record-decision` is not installed, the way-of-working.md write has already succeeded (Step 4) — only the ADL entry (Step 5) is skipped. Warn: "Decision not recorded — /pair-capability-record-decision not installed. Please manually document the PM tool choice." ## Notes diff --git a/.claude/skills/pair-capability-verify-adoption/SKILL.md b/.claude/skills/pair-capability-verify-adoption/SKILL.md index 03e55e7b..ceaf1e1d 100644 --- a/.claude/skills/pair-capability-verify-adoption/SKILL.md +++ b/.claude/skills/pair-capability-verify-adoption/SKILL.md @@ -156,15 +156,15 @@ When invoked **independently**: ## Graceful Degradation -- If an adoption file for a given area does not exist, report that area as `NOT CONFIGURED` — do not fail. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (adoption file missing → report as `NOT CONFIGURED`, don't fail; guideline missing → check only what's derivable) for the standard scenarios. Additional cases: + - If `$scope=all` and no adoption files exist at all, report: "No adoption files found — run `/pair-process-bootstrap` to establish project standards." -- If guidelines referenced by an area are not found, check only adoption-file-derived constraints for that area. - If the codebase is empty or no code changes to check, report all areas as `CONFORMANT` (nothing to violate). ## Notes - This skill is **read-only** — it inspects code and adoption files but never modifies anything. - **Detection-only contract**: the skill identifies non-conformities but never resolves them. Resolution is always delegated to the caller or the appropriate skill. -- **Idempotent**: re-invocation on conformant code immediately confirms compliance. Re-invocation on non-conformant code returns the same findings until the code is fixed. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: conformant code is confirmed immediately; non-conformant code returns the same findings until fixed. - **Scope is mandatory** to prevent accidental full scans when only a targeted check is needed. Use `all` explicitly for comprehensive checks. - Contextual checking: when invoked on a PR, only changes in the PR are checked, not the entire codebase. When invoked independently, the scope of code analysis is determined by the area. diff --git a/.claude/skills/pair-capability-verify-done/SKILL.md b/.claude/skills/pair-capability-verify-done/SKILL.md index 34b4d79e..17be2348 100644 --- a/.claude/skills/pair-capability-verify-done/SKILL.md +++ b/.claude/skills/pair-capability-verify-done/SKILL.md @@ -123,8 +123,8 @@ When invoked **independently**: ## Graceful Degradation -- If [definition-of-done.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-standards/definition-of-done.md) is not found, warn and check only adoption-derived criteria. -- If adoption files are missing, warn and check only universal DoD criteria. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → check only adoption-derived criteria; adoption files missing → check only universal criteria) for the standard scenarios. Additional cases: + - If `$story` is not provided, skip requirements/AC check and evaluate only universal criteria. - If specific guideline files are not found (e.g., security guidelines), skip that criterion group and report: "[Area]: SKIPPED — guidelines not found." - If /pair-capability-verify-quality already ran in the same session, reuse its results for code standards and testing criteria (avoid duplicate work). diff --git a/.claude/skills/pair-capability-verify-quality/SKILL.md b/.claude/skills/pair-capability-verify-quality/SKILL.md index a0d19921..318e00fc 100644 --- a/.claude/skills/pair-capability-verify-quality/SKILL.md +++ b/.claude/skills/pair-capability-verify-quality/SKILL.md @@ -141,8 +141,9 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → run only what's detectable rather than failing) for the standard scenarios. Additional cases: + - If a standard gate command is not available (e.g., no test script in package.json), skip that gate and report: "Tests: SKIPPED — no test command found." -- If [quality-standards](../../../.pair/knowledge/guidelines/quality-assurance/quality-standards/README.md) directory is not found, warn and run only detectable gates (lint, type check, tests from package.json scripts). - If no quality-related scripts are found at all, report: "No quality gates detected. Configure quality gate commands in package.json or way-of-working.md." - If a custom gate command fails to execute (command not found), report as WARNING: "Gate `[name]`: SKIPPED — command not found." - If [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) is not found, skip custom gates entirely (standard gates still run). diff --git a/.claude/skills/pair-capability-write-issue/SKILL.md b/.claude/skills/pair-capability-write-issue/SKILL.md index f98d6c08..4a16efb6 100644 --- a/.claude/skills/pair-capability-write-issue/SKILL.md +++ b/.claude/skills/pair-capability-write-issue/SKILL.md @@ -191,16 +191,16 @@ This skill supports `story`, `task`, `epic`, and `initiative` types. Adding a ne ## Graceful Degradation -- If [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) is not found, HALT — PM tool is required. -- If the template file is not found, HALT — template-driven formatting is mandatory. -- If the PM tool implementation guide is not found, warn and proceed with default behavior. -- If the PM tool is not accessible (auth failure, rate limit, network), HALT with descriptive error — no fallback. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) for the standard scenarios — this skill deliberately **overrides the default degrade behavior with a HALT** for its two load-bearing dependencies: + +- PM tool not configured/accessible, or the template file missing → **HALT** (no fallback — this skill's entire job is writing to the PM tool via a template). +- If the PM tool implementation guide is not found, warn and proceed with default behavior (a genuine degrade, not a HALT). - If `way-of-working.md` has no `## State Mapping` section, canonical macrostate names are assumed for board writes — this is the zero-configuration default, not a degradation. ## Notes - This skill **modifies PM tool state** — it creates and updates issues. -- No PM tool fallback: if the adopted tool fails, the skill HALTs — re-invocation is idempotent (`$id` prevents duplicate creation). +- No PM tool fallback: if the adopted tool fails, the skill HALTs. **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): `$id` prevents duplicate creation on re-invocation. - Template = source of truth for issue body format. Changes to template structure automatically affect all future issue creation. - Labels and hierarchy linking follow the PM tool implementation guide conventions. - **Deliberate tech-debt promotion**: assess-* skills are output-only and never auto-create backlog items. When a debt or quality finding is worth scheduling, a human/agent promotes it here **deliberately** by passing `tech-debt` in `$labels` — a manual, selective act, never a 100% auto-conversion. diff --git a/.claude/skills/pair-next/SKILL.md b/.claude/skills/pair-next/SKILL.md index ad3d0871..22ed73bc 100644 --- a/.claude/skills/pair-next/SKILL.md +++ b/.claude/skills/pair-next/SKILL.md @@ -150,9 +150,9 @@ Then ask: "Shall I run `/skill-name`?" ## Graceful Degradation +See [graceful degradation](../../.pair/knowledge/skill-conventions/graceful-degradation.md) (PM tool not accessible → skip Step 3, recommend from adoption files only; adoption files missing → suggest `/pair-process-bootstrap` as the entry point) for the standard scenarios. Additional cases: + - If a suggested skill is not installed, tell the user which skill is needed and where to find it. -- If the PM tool is not accessible (no MCP connection, no credentials), skip Step 3 and report: "PM tool not accessible — recommendation based on adoption files only." -- If adoption files cannot be read (not installed yet), suggest `/pair-process-bootstrap` as the entry point. - If way-of-working.md has no `## State Mapping` section, canonical macrostate names are assumed — this is the zero-configuration default, not a degradation. - If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 11's condition as unresolvable. diff --git a/.claude/skills/pair-process-bootstrap/SKILL.md b/.claude/skills/pair-process-bootstrap/SKILL.md index 55108add..6a23dbcd 100644 --- a/.claude/skills/pair-process-bootstrap/SKILL.md +++ b/.claude/skills/pair-process-bootstrap/SKILL.md @@ -284,7 +284,7 @@ On HALT: report the blocker clearly, propose resolution, wait for developer. ## Idempotent Re-invocation -Re-invoking `/pair-process-bootstrap` on a partially completed project is safe and expected: +See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/pair-process-bootstrap` on a partially completed project is safe and expected — per-phase: 1. **PRD**: detects existing populated PRD, skips Phase 0. 2. **Categorization**: detects existing ADL entry for `project-categorization`, skips Phase 1. @@ -297,16 +297,18 @@ Phase completion is detected via output file existence — never re-does complet ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill not installed → skip that phase/step with a warning, never blocks) and [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) (`/pair-capability-record-decision` not installed → proposals cannot be persisted, document manually) for the standard scenarios. Additional cases (bootstrap's per-phase optional dependencies): + - **assess-\* skills not installed**: Skip assessment phase, reference guideline files directly, ask developer for manual decisions. Log: "assess-\* skills not installed — using manual assessment." -- **/pair-process-specify-prd not installed**: HALT at Phase 0 if PRD is missing. Suggest creating PRD manually using how-to-01. +- **/pair-process-specify-prd not installed**: HALT at Phase 0 if PRD is missing (a required dependency, not optional). Suggest creating PRD manually using how-to-01. - **/pair-capability-setup-pm not installed**: Skip PM configuration in Phase 4. Warn: "PM tool not configured — /pair-capability-setup-pm not installed." -- **/pair-capability-record-decision not installed**: Adoption cannot be persisted automatically — assess-\* skills are output-only and never write adoption themselves. Warn: "/pair-capability-record-decision not installed — assess-\* proposals cannot be persisted. Write adoption files manually from the proposals and record decisions by hand." - **Bootstrap checklist asset not found**: Use Phase 2 section questions as fallback — they cover the same areas. - **Adoption directory doesn't exist**: Create `adoption/tech/` and `adoption/decision-log/` on first write. +- **/pair-capability-record-decision not installed**: Adoption cannot be persisted automatically — assess-\* skills are output-only and never write adoption themselves. Warn: "/pair-capability-record-decision not installed — assess-\* proposals cannot be persisted. Write adoption files manually from the proposals and record decisions by hand." - **/pair-capability-map-subdomains or /pair-capability-map-contexts not installed**: Skip the corresponding step in Phase 3.5 with a warning. Domain modeling never blocks bootstrap completion. ## Notes -- The developer can stop between phases; re-invoke to resume (idempotency ensures correct state). +- The developer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). - Phase 3.5 is the only full-catalog (`$scope: all`) entry point for `/pair-capability-map-subdomains` and `/pair-capability-map-contexts` — every other caller is scoped to what it just touched. See [Callers Matrix](../../../.pair/knowledge/skills-guide.md#callers-matrix-scoped-capabilities). - Content source: how-to-02 Phases 0-4 (including domain modeling). How-to-02 retains orchestration flow, this skill has operational detail. diff --git a/.claude/skills/pair-process-implement/SKILL.md b/.claude/skills/pair-process-implement/SKILL.md index 5aeb2db8..461b4540 100644 --- a/.claude/skills/pair-process-implement/SKILL.md +++ b/.claude/skills/pair-process-implement/SKILL.md @@ -28,7 +28,7 @@ Implement a user story by processing its tasks sequentially. Each task follows a 1. **Check**: Is the user story already loaded in this session? 2. **Skip**: If yes, confirm story ID and move to Step 0.1b. -3. **Act**: Read the story from the PM tool (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)). +3. **Act**: Read the story from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md). - Understand business value and acceptance criteria. - Confirm epic context. 4. **Verify**: Story is fully loaded. If not → **HALT**. @@ -393,7 +393,7 @@ On HALT: report the blocker clearly, propose resolution, wait for developer. ## Idempotent Re-invocation -Re-invoking `/pair-process-implement` on a partially completed story is safe and expected: +See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/pair-process-implement` on a partially completed story is safe and expected — per-step: 1. **Branch**: detects existing branch, switches to it. 2. **Commit strategy**: if commits already exist on branch, infer strategy from history. @@ -406,16 +406,16 @@ The skill resumes from the first incomplete step — never re-does completed wor ## Graceful Degradation -- **PM tool not accessible**: Ask developer to manually provide story details and task list. -- **Missing adoption files**: Warn and proceed with guideline defaults. -- **/assess-stack not installed**: Warn on new dependency, continue without validation. -- **/verify-adoption not installed**: Warn, skip adoption compliance check. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (PM tool not accessible → ask the developer directly; adoption file missing → proceed with guideline defaults) for the standard scenarios. Additional cases: + +- **`/pair-capability-assess-stack` not installed**: Warn on new dependency, continue without validation. +- **`/pair-capability-verify-adoption` not installed**: Warn, skip adoption compliance check. - **No quality gate command**: Fall back to individual checks (lint, test, type check). ## Notes - This skill **modifies files and creates git artifacts** (branches, commits, PRs). - Task iteration is sequential — each task completes its full cycle before the next begins. -- The developer can stop between tasks; re-invoke to resume (idempotency ensures correct state). +- The developer can stop between tasks; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). - Single PR per story regardless of commit strategy. - **Squash happens at merge** (Phase 4), not before PR creation. Individual commits are preserved on the branch during review. diff --git a/.claude/skills/pair-process-plan-epics/SKILL.md b/.claude/skills/pair-process-plan-epics/SKILL.md index f38c1f32..ab3b6539 100644 --- a/.claude/skills/pair-process-plan-epics/SKILL.md +++ b/.claude/skills/pair-process-plan-epics/SKILL.md @@ -135,12 +135,13 @@ EPICS COMPLETE: ## Graceful Degradation -- If `/pair-capability-write-issue` is not installed, warn and provide formatted epic content for manual PM tool entry. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/pair-capability-write-issue` not installed / PM tool not accessible → produce epic documents, ask developer to create manually) for the standard scenarios. Additional cases: + +- If `/pair-capability-map-subdomains` is not installed, skip Step 3.5 with a warning — epic creation proceeds without domain mapping. - If bounded contexts are not defined, proceed with PRD and initiative analysis only. -- If PM tool is not accessible, produce epic documents and ask developer to create manually. ## Notes - This skill **modifies PM tool state** — creates epic issues linked to initiatives. -- Idempotent: re-invocation detects existing epics and skips them. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing epics and skips them. - Epic 0 rule: for new projects, always assess if a bootstrap/foundation epic is needed before functional epics. diff --git a/.claude/skills/pair-process-plan-initiatives/SKILL.md b/.claude/skills/pair-process-plan-initiatives/SKILL.md index fc5e5485..6b81e094 100644 --- a/.claude/skills/pair-process-plan-initiatives/SKILL.md +++ b/.claude/skills/pair-process-plan-initiatives/SKILL.md @@ -134,12 +134,12 @@ INITIATIVES COMPLETE: ## Graceful Degradation -- If `/pair-capability-write-issue` is not installed, warn and provide formatted initiative content for manual PM tool entry. -- If the PM tool is not accessible, produce initiative documents and ask developer to create manually. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/pair-capability-write-issue` not installed / PM tool not accessible → produce initiative documents, ask developer to create manually) for the standard scenarios. Additional cases: + - If adoption files (architecture, tech-stack) are missing, proceed with PRD analysis only and warn. ## Notes - This skill **modifies PM tool state** — creates initiative issues. -- Idempotent: re-invocation detects existing initiatives by title matching and skips them. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing initiatives by title matching and skips them. - Initiative = highest-level work item. Hierarchy: initiative → epic → story → task. diff --git a/.claude/skills/pair-process-plan-stories/SKILL.md b/.claude/skills/pair-process-plan-stories/SKILL.md index e803ab2e..811d2ff7 100644 --- a/.claude/skills/pair-process-plan-stories/SKILL.md +++ b/.claude/skills/pair-process-plan-stories/SKILL.md @@ -149,13 +149,13 @@ STORIES COMPLETE: ## Graceful Degradation -- If `/pair-capability-write-issue` is not installed, warn and provide formatted story content for manual PM tool entry. -- If PM tool is not accessible, produce story documents and ask developer to create manually. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/pair-capability-write-issue` not installed / PM tool not accessible → produce story documents, ask developer to create/enter manually) for the standard scenarios. Additional cases: + - If epic documentation is sparse, proceed with available context and flag gaps. ## Notes - This skill **modifies PM tool state** — creates story issues linked to epics. -- Idempotent: re-invocation detects existing stories and skips them. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing stories and skips them. - Stories at breakdown stage are rough planning units — detailed requirements are added during `/pair-process-refine-story`. - INVEST validation is mandatory — stories failing INVEST must be reworked before creation. diff --git a/.claude/skills/pair-process-plan-tasks/SKILL.md b/.claude/skills/pair-process-plan-tasks/SKILL.md index eb0f2886..0ba2f326 100644 --- a/.claude/skills/pair-process-plan-tasks/SKILL.md +++ b/.claude/skills/pair-process-plan-tasks/SKILL.md @@ -149,13 +149,13 @@ TASK BREAKDOWN COMPLETE: ## Graceful Degradation -- If `/pair-capability-write-issue` is not installed, warn and provide the formatted Task Breakdown section for manual PM tool update. -- If the PM tool is not accessible, produce the task breakdown content and ask the developer to update manually. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/pair-capability-write-issue` not installed / PM tool not accessible → produce the task breakdown content, ask developer to update manually) for the standard scenarios. Additional cases: + - If adoption files (architecture, tech-stack, bounded contexts) are not found, skip technical context alignment and warn. ## Notes - This skill **modifies PM tool state** — it updates the story body with the Task Breakdown section. No separate task issues are created. -- Task-level idempotency: re-invoking on a story with partial tasks appends only missing ones to the story body. +- **Idempotent (task-level)** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-invoking on a story with partial tasks appends only missing ones to the story body. - Condensed TA removes verbose implementation detail that belongs in individual tasks (retained items: see Step 5). - Story template reference: [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md). diff --git a/.claude/skills/pair-process-refine-story/SKILL.md b/.claude/skills/pair-process-refine-story/SKILL.md index 88848f35..c3b8ce1a 100644 --- a/.claude/skills/pair-process-refine-story/SKILL.md +++ b/.claude/skills/pair-process-refine-story/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /pair-process-refine-story — Story Refinement -Transform a user story from rough breakdown (Todo) into a development-ready specification (Refined). Section-level idempotency: each refinement section is checked before acting — partial refinements resume from the first missing section. +Transform a user story from rough breakdown (Todo) into a development-ready specification (Refined). **Section-level idempotency** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): each refinement section is checked before acting; partial refinements resume from the first missing section. ## Composed Skills @@ -157,8 +157,8 @@ STORY REFINEMENT COMPLETE: ## Graceful Degradation -- If `/pair-capability-write-issue` is not installed, warn and provide the formatted story body for manual PM tool update. -- If the PM tool is not accessible, produce the refined story content and ask the developer to update manually. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/pair-capability-write-issue` not installed / PM tool not accessible → produce the refined story content, ask developer to update manually) for the standard scenarios. Additional cases: + - If adoption files (architecture, tech-stack) are not found, skip technical analysis alignment checks and warn. - If `context-map.md` is not found, skip the domain check in Step 2 — its absence is the expected steady state, not an error. diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 0aca98a1..2fd5c97f 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -49,7 +49,7 @@ CODE REVIEW STATE: 1. **Check**: Is the PR already loaded in this session? 2. **Skip**: If yes, confirm PR number and move to Step 1.2. -3. **Act**: Read PR from the PM tool (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)): +3. **Act**: Read PR from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md): - PR metadata (author, branch, target, status) - Changed files and diff - PR description and linked story @@ -360,7 +360,7 @@ On HALT: report the blocker, compose the resolution skill if available, wait for ## Idempotent Re-invocation -Re-invoking `/pair-process-review` on a partially reviewed PR is safe: +See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/pair-process-review` on a partially reviewed PR is safe — per-phase: 1. **PR context**: detects already-loaded PR, skips re-loading. 2. **Phases**: checks which phases completed (via session state or PR review comments). Resumes from first incomplete phase. @@ -371,12 +371,14 @@ Re-invoking `/pair-process-review` on a partially reviewed PR is safe: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill not installed → degrade, never HALT; PM tool not accessible → ask the reviewer directly) for the standard scenarios. Additional cases: + - **/pair-capability-verify-adoption not installed**: Falls back to inline dependency checking against [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md). Warning logged. See degradation cascade (Phase 3). - **/pair-capability-assess-stack not installed**: Unlisted dependencies flagged as warnings for manual verification. Does NOT HALT. - **/pair-capability-analyze-debt not available**: Skip debt assessment, note in report. - **Story not found**: Review proceeds with PR-only validation (no AC check). Phase 6 skips parent cascade. -- **Code review template not found**: **HALT** — cannot produce review without template. -- **PM tool not accessible**: Ask reviewer to manually provide PR details. Phase 6 merge via CLI only. +- **Code review template not found**: **HALT** — cannot produce review without template (a required dependency, not optional). +- **PM tool not accessible**: Phase 6 merge via CLI only. - **Merge fails** (conflicts, branch protection): Report the failure, ask reviewer to resolve. Do not force-push or bypass protections. - **/pair-capability-execute-manual-tests not installed**: Skip Step 6.6. Log "Manual test validation skipped — skill not installed." Does NOT block merge. - **No manual test suite**: Skip Step 6.6. Log "No manual test suite found." Does NOT block merge. @@ -385,7 +387,7 @@ Re-invoking `/pair-process-review` on a partially reviewed PR is safe: - This skill **reads code, posts review comments, and optionally merges PRs** — it does not modify source code. - Review phases are sequential — each phase builds on findings from prior phases. -- The reviewer can stop between phases; re-invoke to resume (idempotency ensures correct state). +- The reviewer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). - Output follows [code-review-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/code-review-template.md) — the template defines structure, /pair-process-review fills it with findings. - HALT on missing ADR is inherited from [how-to-11](../../../.pair/knowledge/how-to/11-how-to-code-review.md) — this is a business rule, not a skill limitation. - **Parent cascade is best-effort** — if sub-issue queries fail, the skill reports which updates need manual attention. diff --git a/.claude/skills/pair-process-specify-prd/SKILL.md b/.claude/skills/pair-process-specify-prd/SKILL.md index 98cf847b..0d70c565 100644 --- a/.claude/skills/pair-process-specify-prd/SKILL.md +++ b/.claude/skills/pair-process-specify-prd/SKILL.md @@ -180,6 +180,8 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (reference material missing → use a minimal structure directly; adoption directory missing → the skill still runs, creates it) for the standard scenarios. Additional cases: + - If [PRD template](../../../.pair/knowledge/assets/PRD_template.md) not found, use the 13-section structure defined in Phase 1 Step 1.2 checklist as a minimal template. - If [PRD example](../../../.pair/knowledge/assets/PRD_example.md) not found, proceed without quality reference but warn: "No PRD example found — quality benchmarking unavailable." - If adoption directory doesn't exist, create `adoption/product/` and warn: "Created adoption directory — this appears to be a new project." diff --git a/.pair/knowledge/skill-conventions/README.md b/.pair/knowledge/skill-conventions/README.md new file mode 100644 index 00000000..efd0790e --- /dev/null +++ b/.pair/knowledge/skill-conventions/README.md @@ -0,0 +1,24 @@ +# Skill Conventions — Shared KB References + +Single-source explanations for patterns that recur across many `SKILL.md` files. Each skill keeps only its **delta** (the part genuinely specific to it) and points here for the generic mechanics — so a convention is edited in one place, not re-derived per skill. + +| Convention | File | Restated in (before this pass) | +| --- | --- | --- | +| Resolution cascade (Argument > Adoption > Assessment) | [resolution-cascade.md](resolution-cascade.md) | 10 skills | +| Idempotency | [idempotency.md](idempotency.md) | 28 skills | +| Graceful degradation | [graceful-degradation.md](graceful-degradation.md) | 34 skills | +| Way-of-working / PM-tool resolution | [way-of-working-pm-resolution.md](way-of-working-pm-resolution.md) | 18 skills | +| `/pair-capability-record-decision` invocation contract | [record-decision-contract.md](record-decision-contract.md) | 19 skills | +| Output Format shapes (Decision / Report) | [output-shapes.md](output-shapes.md) | 10 skills (documentation-only — no logic change) | + +## How a skill uses these files + +A skill's own section keeps its heading (e.g. `### Step 1: Resolution Cascade`, `## Graceful Degradation`) and states its **delta only**, then points here for the generic mechanics, e.g.: + +> See [resolution cascade](resolution-cascade.md) for the generic Path A/B/C mechanics. **This skill's Path B**: ... + +This is a context pointer, not a citation: the executor is expected to follow it when it reaches that step, the same way it already follows pointers to guideline files elsewhere in the algorithm. If a pointer ever proves unreliable for must-have material, sharpen its wording first — inline the content again only if sharpening fails. + +## Scope note + +These files are **generic and portable** — like the rest of `.pair/knowledge/`, they describe how *this skill corpus* works, not any one project's history. They may name skills, arguments, and adoption-file conventions; they never cite this repo's own ADRs, decision-log entries, or issue numbers as authority for the convention itself. diff --git a/.pair/knowledge/skill-conventions/graceful-degradation.md b/.pair/knowledge/skill-conventions/graceful-degradation.md new file mode 100644 index 00000000..fe21ba9f --- /dev/null +++ b/.pair/knowledge/skill-conventions/graceful-degradation.md @@ -0,0 +1,20 @@ +# Graceful Degradation — Standard Bullets + +A skill's `## Graceful Degradation` section lists what happens when something it depends on is missing or unreachable. Four scenarios recur near-verbatim across the corpus — state them once here; a skill's own section keeps only the bullets that are genuinely specific to it (a different guideline file, a domain-specific fallback question, etc.). + +**Rule of thumb**: degrade (don't HALT) when the missing thing is *optional context or an optional composed skill*; HALT only when the missing thing is *load-bearing* (e.g. a required template, a required composed skill, or the operation is meaningless without it). + +## The four standard scenarios + +1. **Guideline/reference file not found** → fall back to a minimal assessment: ask the developer directly for the preference/input the guideline would otherwise have informed, rather than failing. +2. **Adoption file (or the section this skill owns) doesn't exist yet** → the skill still runs and produces its proposal/report; for a writing skill, the caller creates the file on persist. Never treated as a failure — adoption files start empty by design. +3. **An optional composed skill is not installed** → skip that composed step, fall back to the inline/manual equivalent (or note the gap in the output), and continue. Only a **required** composed skill (per the skill's own Composed Skills table) HALTs when missing. +4. **The PM tool is not accessible** (no MCP connection, no credentials, API error) → ask the developer to provide the needed information manually, or proceed with the parts of the task that don't need the PM tool; never silently guess PM-tool state. See [way-of-working-pm-resolution.md](way-of-working-pm-resolution.md). + +## What stays in the skill (the delta) + +Only bullets that describe a scenario **not** covered above — e.g. a domain-specific fallback ("if no PRD, use the Decision Matrix to recommend a methodology anyway"), or a skill-specific hard requirement that escalates one of the four scenarios to a HALT instead of a degrade. State the pointer once at the top of the section: + +> See [graceful degradation](graceful-degradation.md) for the standard scenarios (guideline missing, adoption file missing, optional skill not installed, PM tool unreachable). This skill's additional cases: + +then list only what's additional or a deliberate override of the default (don't-HALT vs HALT) behavior. diff --git a/.pair/knowledge/skill-conventions/idempotency.md b/.pair/knowledge/skill-conventions/idempotency.md new file mode 100644 index 00000000..cd108919 --- /dev/null +++ b/.pair/knowledge/skill-conventions/idempotency.md @@ -0,0 +1,20 @@ +# Idempotency Convention + +Re-invoking a skill that already produced its output is always safe: the skill **detects** the existing artifact (file, adoption section, PM-tool state, prior report) and **confirms** it rather than blindly redoing the work. Redo only happens on an **explicit** request — never as the default. + +This is the general shape: + +1. **Check**: Does the artifact this invocation would produce already exist (in whole or in part)? +2. **Skip**: If it doesn't exist yet, proceed with the normal (first-run) algorithm. +3. **Act**: If it exists, present it and confirm it's still valid/current — do not regenerate. +4. **Verify**: Confirmed → exit (or resume from the first missing piece, for multi-part artifacts). Explicit redo request → proceed with regeneration. + +## What stays in the skill (the delta) + +The **generic shape above never needs restating**. Every skill keeps only the one line that says what the artifact is and how re-invocation detects it — e.g. "detects existing files by filename", "shows current state instead of re-creating", "task-level: appends only missing tasks". That one line is the entire per-skill delta; write it as a single Notes bullet: + +> **Idempotent** — see [idempotency convention](idempotency.md). This skill's check: ``. + +## Orchestrators (multi-phase skills) + +The three orchestrators (`/pair-process-bootstrap`, `/pair-process-implement`, `/pair-process-review`) resume **per-phase/per-task**, not as a single artifact check. They keep their own itemized resume list (which phase/task is detected as done and skipped) — that list is genuinely skill-specific and is not duplicated elsewhere. Only the generic framing sentence ("re-invoking `/X` on a partially completed run is safe and expected") and the closing "idempotency ensures correct state" reminder are boilerplate — those point here instead of restating the convention. diff --git a/.pair/knowledge/skill-conventions/output-shapes.md b/.pair/knowledge/skill-conventions/output-shapes.md new file mode 100644 index 00000000..1650c18a --- /dev/null +++ b/.pair/knowledge/skill-conventions/output-shapes.md @@ -0,0 +1,50 @@ +# Output Format Shapes + +Two named ASCII shapes formalize what the `assess-*`/`analyze-*` family already produces de facto and identically. This is documentation of an existing convention — no skill's output logic changes; a new skill in either family inherits the right shape by reference instead of re-deriving one. + +## Decision Shape + +Used by the 8 **decision** skills — `assess-ai`, `assess-architecture`, `assess-infrastructure`, `assess-methodology`, `assess-observability`, `assess-pm`, `assess-stack`, `assess-testing`. Each proposes a choice to be persisted via [`/pair-capability-record-decision`](record-decision-contract.md). + +```text +ASSESSMENT COMPLETE (output-only — no files written): +├── Domain: [assessment domain, e.g. Architecture, Testing] +├── Path: [Argument Override | Adoption Exists | Full Assessment] +├── Decision: [the recommended choice, in domain-specific terms] +├── Proposal: [content rendered for ] +├── Target: () +├── Persist: [caller composes /pair-capability-record-decision(content, target) → ADR|ADL] +└── Status: [Proposal ready | Confirmed existing] +``` + +Per-skill delta: the `Domain` label, the `Decision`/`Proposal`/`Target` line contents, and the ADR-vs-ADL choice in `Persist`. `assess-stack` additionally carries a `Mode` line (Bootstrap | Implementation | Review) and a wider `Status` set (adds Approved | Rejected) because it spans the whole project lifecycle, not just bootstrap. `assess-pm` additionally carries a `Delegated` status because it may hand persistence to `/pair-capability-setup-pm`. Both are legitimate deltas, not shape violations. + +## Report Shape + +Used by the 2 **report** skills — `analyze-debt`, `analyze-code-quality`. Each returns findings for the caller to read; neither proposes an adoption change or persists anything. + +```text + (output-only — no files [or issues] created): +├── +├── +... +└── + +: +1. [item] — [detail] — [recommendation or scoring] +2. ... + + (when applicable): +1. [priority] [action] +2. ... + +RESULT: [one-line outcome — report only, nothing created/blocked] +``` + +Per-skill delta: the metrics collected (debt counts by category/severity vs. complexity/size/coverage/duplication/maintainability), the items-section framing (prioritized debt items vs. hotspots), and whether a distinct recommendations block is present. + +## Choosing a shape for a new skill + +- Proposes a choice for `/pair-capability-record-decision` to persist → **Decision Shape**. +- Returns findings/metrics with no adoption proposal → **Report Shape**. +- Neither fits → don't force one; a genuinely different skill kind gets its own Output Format, not a bent version of these two. diff --git a/.pair/knowledge/skill-conventions/record-decision-contract.md b/.pair/knowledge/skill-conventions/record-decision-contract.md new file mode 100644 index 00000000..c0fe2584 --- /dev/null +++ b/.pair/knowledge/skill-conventions/record-decision-contract.md @@ -0,0 +1,53 @@ +# `/pair-capability-record-decision` Invocation Contract + +`/pair-capability-record-decision` is the **sole generic writer of adoption files** (the one exception is `/pair-capability-setup-pm`, which writes the PM section of way-of-working.md itself and composes `/pair-capability-record-decision` only for the decision record). Every `assess-*` skill, and any orchestrator that accepts an `assess-*` proposal, follows the same contract — stated once here. + +## The tuple + +An `assess-*` skill never writes. It returns: + +```text +{ content, target, decision-metadata } +``` + +- **`content`** — the rendered adoption content (ready to write, scoped to the section this skill owns). +- **`target`** — the adoption file/section that content is destined for (e.g. `adoption/tech/tech-stack.md`, AI section). +- **`decision-metadata`** — `$type` (architectural | non-architectural | domain), `$topic` (kebab-case), `$summary` (one line) — the arguments `/pair-capability-record-decision` needs to classify and file the decision. + +The caller (the orchestrator or the human/agent invoking the assess-* skill directly) persists by composing: + +```text +/pair-capability-record-decision(content, target, decision-metadata) +``` + +which writes `content` into its owned section of `target` (a heading-scoped merge — it preserves the rest of the file) and records the ADR/ADL/DDR per its own classification rule. + +## Standard "Verify" line (end of Path A/B in the resolution cascade, and end of the assessment step) + +> **Verify**: Proposal emitted. Persistence is performed by the caller via `/pair-capability-record-decision(content, target, decision-metadata)`, never by this skill. + +## Standard Composition Interface shape + +```markdown +When composed by `/pair-process-bootstrap`: + +- **Input**: `/pair-process-bootstrap` invokes during Phase 2[, with ]. +- **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 and record the . + +When invoked **independently**: + +- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits. +``` + +Additional "When composed by ..." blocks (e.g. `/pair-process-implement`, `/pair-process-review` for `/pair-capability-assess-stack`'s implementation/review modes) follow the same Input/Output/Persistence shape — only the caller name, trigger, and target/ADR-vs-ADL vary. + +## Standard degradation bullet + +> If the caller cannot persist (e.g. `/pair-capability-record-decision` not installed), the proposal stands as a report — adoption stays unchanged. + +## What stays in the skill (the delta) + +- The exact `target` file/section and the `decision-metadata` values (`$type`, `$topic`, `$summary` template) for that domain — these are the whole point of each assess-* skill and never move out. +- Whether the decision is typically architectural or non-architectural for that domain, and the exception condition when it flips (e.g. "testing decisions are non-architectural, exception: contract testing requiring service boundaries") — this is domain judgment, not boilerplate; it stays as a Notes bullet, `/pair-capability-record-decision`'s own classification gate (Step 1) still runs regardless. +- Section-ownership notes (which skill owns which part of a shared file). diff --git a/.pair/knowledge/skill-conventions/resolution-cascade.md b/.pair/knowledge/skill-conventions/resolution-cascade.md new file mode 100644 index 00000000..7f690bee --- /dev/null +++ b/.pair/knowledge/skill-conventions/resolution-cascade.md @@ -0,0 +1,34 @@ +# Resolution Cascade + +The generic priority order a skill uses to decide **how much work it still needs to do**, before running its full algorithm: an explicit argument wins over existing adoption, which wins over a fresh assessment. Three paths, always evaluated in order, each following **check → skip → act → verify**. + +## Path A — Argument Override + +1. **Check**: Is the skill's override argument (typically `$choice`) provided? +2. **Skip**: If not provided, go to Path B. +3. **Act**: Confirm the override with the developer — surface any conflict with existing adoption before accepting it. +4. **Verify**: Developer confirms. Proceed to the skill's main algorithm (skip guideline-reading/assessment). + +## Path B — Existing State Check + +Two variants, depending on the skill's nature: + +- **Decision skills** (the `assess-*` family): Path B checks whether the relevant **adoption file/section already exists and is populated**. If yes: read it, confirm it's still valid, check a corresponding decision record exists (ADR/ADL — see [record-decision-contract.md](record-decision-contract.md)), report a gap if missing, then exit — the resolution cascade **is** the idempotency mechanism for these skills (adoption already reflects the decision, so there's nothing left to assess). +- **Report/analysis skills** (e.g. an `analyze-*` skill): Path B checks whether a **recent output already exists** (report, prior analysis) instead of an adoption file. If found and not stale, confirm and exit; if stale or the developer requests it, proceed to Path C. This variant is the [idempotency convention](idempotency.md) applied at Step 1. + +1. **Check**: Does the relevant existing state (adoption section, or recent report) exist and hold? +2. **Skip**: If not, go to Path C. +3. **Act**: Present the existing state; ask whether to keep it or redo. +4. **Verify**: If kept → exit skill. If redo requested (or state is stale/missing) → proceed to Path C. + +## Path C — Full Assessment/Analysis + +1. **Act**: Proceed to the skill's main algorithm (read guidelines, evaluate, produce the proposal or report). + +## Per-skill delta (what stays in the skill, not here) + +Only these vary per skill and belong in the skill's own `### Step 1: Resolution Cascade` section, right after the pointer to this file: + +- Which adoption file/section (or which "existing output" signal) Path B checks against. +- The exact confirmation/HALT prompt wording for that domain. +- Which step number Path C proceeds to (depends on the skill's own algorithm layout). diff --git a/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md b/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md new file mode 100644 index 00000000..6b3c8ef7 --- /dev/null +++ b/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md @@ -0,0 +1,21 @@ +# Way-of-Working / PM-Tool Resolution + +How any skill that needs the project's PM tool (to read or write a story/PR/epic) determines **which tool it is and how to reach it**, and how it translates board-specific state into the canonical vocabulary the corpus uses. + +## PM tool discovery + +1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) and identify the adopted PM tool (GitHub Projects, Jira, Linear, etc.) and its access method. +2. **Skip**: If found, proceed with that tool. +3. **Act**: If no PM tool is configured, **HALT**: + + > No PM tool configured in `way-of-working.md`. Configure via `/pair-capability-setup-pm`, or manually set the PM tool in way-of-working.md. + +4. **Verify**: PM tool identified and reachable (or the HALT above has been surfaced). + +## State resolution (macrostates) + +Skills refer to **canonical macrostates** (`Draft`, `Ready`, `In Progress`, `Review`, `Done`) — never board-specific column/label names. Resolve an item's actual board state to a macrostate via the `## State Mapping` section in way-of-working.md; if that section is omitted, canonical names are assumed (zero-configuration default, not a degradation). See [canonical-states.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/canonical-states.md) for the full resolution rule, including the **Readiness Fallback**: when a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), evaluate Definition-of-Ready criteria against the item instead of guessing from the board-state name. + +## What stays in the skill (the delta) + +Most skills only need a short pointer where they read/write the PM tool — e.g. "Read the story from the PM tool (resolution: see [way-of-working-pm-resolution.md](way-of-working-pm-resolution.md))" — because `/pair-capability-write-issue` is the actual PM-tool writer for creation/update flows and already implements the discovery+HALT logic above in full. A skill only needs to **restate** the full discovery+HALT block (Steps 1-4 above) if it talks to the PM tool directly rather than delegating to `/pair-capability-write-issue` — keep that as the delta; everything else points here. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/README.md b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/README.md new file mode 100644 index 00000000..0810da4b --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/README.md @@ -0,0 +1,24 @@ +# Skill Conventions — Shared KB References + +Single-source explanations for patterns that recur across many `SKILL.md` files. Each skill keeps only its **delta** (the part genuinely specific to it) and points here for the generic mechanics — so a convention is edited in one place, not re-derived per skill. + +| Convention | File | Restated in (before this pass) | +| --- | --- | --- | +| Resolution cascade (Argument > Adoption > Assessment) | [resolution-cascade.md](resolution-cascade.md) | 10 skills | +| Idempotency | [idempotency.md](idempotency.md) | 28 skills | +| Graceful degradation | [graceful-degradation.md](graceful-degradation.md) | 34 skills | +| Way-of-working / PM-tool resolution | [way-of-working-pm-resolution.md](way-of-working-pm-resolution.md) | 18 skills | +| `/record-decision` invocation contract | [record-decision-contract.md](record-decision-contract.md) | 19 skills | +| Output Format shapes (Decision / Report) | [output-shapes.md](output-shapes.md) | 10 skills (documentation-only — no logic change) | + +## How a skill uses these files + +A skill's own section keeps its heading (e.g. `### Step 1: Resolution Cascade`, `## Graceful Degradation`) and states its **delta only**, then points here for the generic mechanics, e.g.: + +> See [resolution cascade](resolution-cascade.md) for the generic Path A/B/C mechanics. **This skill's Path B**: ... + +This is a context pointer, not a citation: the executor is expected to follow it when it reaches that step, the same way it already follows pointers to guideline files elsewhere in the algorithm. If a pointer ever proves unreliable for must-have material, sharpen its wording first — inline the content again only if sharpening fails. + +## Scope note + +These files are **generic and portable** — like the rest of `.pair/knowledge/`, they describe how *this skill corpus* works, not any one project's history. They may name skills, arguments, and adoption-file conventions; they never cite this repo's own ADRs, decision-log entries, or issue numbers as authority for the convention itself. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/graceful-degradation.md b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/graceful-degradation.md new file mode 100644 index 00000000..fe21ba9f --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/graceful-degradation.md @@ -0,0 +1,20 @@ +# Graceful Degradation — Standard Bullets + +A skill's `## Graceful Degradation` section lists what happens when something it depends on is missing or unreachable. Four scenarios recur near-verbatim across the corpus — state them once here; a skill's own section keeps only the bullets that are genuinely specific to it (a different guideline file, a domain-specific fallback question, etc.). + +**Rule of thumb**: degrade (don't HALT) when the missing thing is *optional context or an optional composed skill*; HALT only when the missing thing is *load-bearing* (e.g. a required template, a required composed skill, or the operation is meaningless without it). + +## The four standard scenarios + +1. **Guideline/reference file not found** → fall back to a minimal assessment: ask the developer directly for the preference/input the guideline would otherwise have informed, rather than failing. +2. **Adoption file (or the section this skill owns) doesn't exist yet** → the skill still runs and produces its proposal/report; for a writing skill, the caller creates the file on persist. Never treated as a failure — adoption files start empty by design. +3. **An optional composed skill is not installed** → skip that composed step, fall back to the inline/manual equivalent (or note the gap in the output), and continue. Only a **required** composed skill (per the skill's own Composed Skills table) HALTs when missing. +4. **The PM tool is not accessible** (no MCP connection, no credentials, API error) → ask the developer to provide the needed information manually, or proceed with the parts of the task that don't need the PM tool; never silently guess PM-tool state. See [way-of-working-pm-resolution.md](way-of-working-pm-resolution.md). + +## What stays in the skill (the delta) + +Only bullets that describe a scenario **not** covered above — e.g. a domain-specific fallback ("if no PRD, use the Decision Matrix to recommend a methodology anyway"), or a skill-specific hard requirement that escalates one of the four scenarios to a HALT instead of a degrade. State the pointer once at the top of the section: + +> See [graceful degradation](graceful-degradation.md) for the standard scenarios (guideline missing, adoption file missing, optional skill not installed, PM tool unreachable). This skill's additional cases: + +then list only what's additional or a deliberate override of the default (don't-HALT vs HALT) behavior. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/idempotency.md b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/idempotency.md new file mode 100644 index 00000000..bb729bd8 --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/idempotency.md @@ -0,0 +1,20 @@ +# Idempotency Convention + +Re-invoking a skill that already produced its output is always safe: the skill **detects** the existing artifact (file, adoption section, PM-tool state, prior report) and **confirms** it rather than blindly redoing the work. Redo only happens on an **explicit** request — never as the default. + +This is the general shape: + +1. **Check**: Does the artifact this invocation would produce already exist (in whole or in part)? +2. **Skip**: If it doesn't exist yet, proceed with the normal (first-run) algorithm. +3. **Act**: If it exists, present it and confirm it's still valid/current — do not regenerate. +4. **Verify**: Confirmed → exit (or resume from the first missing piece, for multi-part artifacts). Explicit redo request → proceed with regeneration. + +## What stays in the skill (the delta) + +The **generic shape above never needs restating**. Every skill keeps only the one line that says what the artifact is and how re-invocation detects it — e.g. "detects existing files by filename", "shows current state instead of re-creating", "task-level: appends only missing tasks". That one line is the entire per-skill delta; write it as a single Notes bullet: + +> **Idempotent** — see [idempotency convention](idempotency.md). This skill's check: ``. + +## Orchestrators (multi-phase skills) + +The three orchestrators (`/bootstrap`, `/implement`, `/review`) resume **per-phase/per-task**, not as a single artifact check. They keep their own itemized resume list (which phase/task is detected as done and skipped) — that list is genuinely skill-specific and is not duplicated elsewhere. Only the generic framing sentence ("re-invoking `/X` on a partially completed run is safe and expected") and the closing "idempotency ensures correct state" reminder are boilerplate — those point here instead of restating the convention. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/output-shapes.md b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/output-shapes.md new file mode 100644 index 00000000..40e23b5f --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/output-shapes.md @@ -0,0 +1,50 @@ +# Output Format Shapes + +Two named ASCII shapes formalize what the `assess-*`/`analyze-*` family already produces de facto and identically. This is documentation of an existing convention — no skill's output logic changes; a new skill in either family inherits the right shape by reference instead of re-deriving one. + +## Decision Shape + +Used by the 8 **decision** skills — `assess-ai`, `assess-architecture`, `assess-infrastructure`, `assess-methodology`, `assess-observability`, `assess-pm`, `assess-stack`, `assess-testing`. Each proposes a choice to be persisted via [`/record-decision`](record-decision-contract.md). + +```text +ASSESSMENT COMPLETE (output-only — no files written): +├── Domain: [assessment domain, e.g. Architecture, Testing] +├── Path: [Argument Override | Adoption Exists | Full Assessment] +├── Decision: [the recommended choice, in domain-specific terms] +├── Proposal: [content rendered for ] +├── Target: () +├── Persist: [caller composes /record-decision(content, target) → ADR|ADL] +└── Status: [Proposal ready | Confirmed existing] +``` + +Per-skill delta: the `Domain` label, the `Decision`/`Proposal`/`Target` line contents, and the ADR-vs-ADL choice in `Persist`. `assess-stack` additionally carries a `Mode` line (Bootstrap | Implementation | Review) and a wider `Status` set (adds Approved | Rejected) because it spans the whole project lifecycle, not just bootstrap. `assess-pm` additionally carries a `Delegated` status because it may hand persistence to `/setup-pm`. Both are legitimate deltas, not shape violations. + +## Report Shape + +Used by the 2 **report** skills — `analyze-debt`, `analyze-code-quality`. Each returns findings for the caller to read; neither proposes an adoption change or persists anything. + +```text + (output-only — no files [or issues] created): +├── +├── +... +└── + +: +1. [item] — [detail] — [recommendation or scoring] +2. ... + + (when applicable): +1. [priority] [action] +2. ... + +RESULT: [one-line outcome — report only, nothing created/blocked] +``` + +Per-skill delta: the metrics collected (debt counts by category/severity vs. complexity/size/coverage/duplication/maintainability), the items-section framing (prioritized debt items vs. hotspots), and whether a distinct recommendations block is present. + +## Choosing a shape for a new skill + +- Proposes a choice for `/record-decision` to persist → **Decision Shape**. +- Returns findings/metrics with no adoption proposal → **Report Shape**. +- Neither fits → don't force one; a genuinely different skill kind gets its own Output Format, not a bent version of these two. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/record-decision-contract.md b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/record-decision-contract.md new file mode 100644 index 00000000..3a3eba06 --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/record-decision-contract.md @@ -0,0 +1,53 @@ +# `/record-decision` Invocation Contract + +`/record-decision` is the **sole generic writer of adoption files** (the one exception is `/setup-pm`, which writes the PM section of way-of-working.md itself and composes `/record-decision` only for the decision record). Every `assess-*` skill, and any orchestrator that accepts an `assess-*` proposal, follows the same contract — stated once here. + +## The tuple + +An `assess-*` skill never writes. It returns: + +```text +{ content, target, decision-metadata } +``` + +- **`content`** — the rendered adoption content (ready to write, scoped to the section this skill owns). +- **`target`** — the adoption file/section that content is destined for (e.g. `adoption/tech/tech-stack.md`, AI section). +- **`decision-metadata`** — `$type` (architectural | non-architectural | domain), `$topic` (kebab-case), `$summary` (one line) — the arguments `/record-decision` needs to classify and file the decision. + +The caller (the orchestrator or the human/agent invoking the assess-* skill directly) persists by composing: + +```text +/record-decision(content, target, decision-metadata) +``` + +which writes `content` into its owned section of `target` (a heading-scoped merge — it preserves the rest of the file) and records the ADR/ADL/DDR per its own classification rule. + +## Standard "Verify" line (end of Path A/B in the resolution cascade, and end of the assessment step) + +> **Verify**: Proposal emitted. Persistence is performed by the caller via `/record-decision(content, target, decision-metadata)`, never by this skill. + +## Standard Composition Interface shape + +```markdown +When composed by `/bootstrap`: + +- **Input**: `/bootstrap` invokes during Phase 2[, with ]. +- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing. +- **Persistence**: `/bootstrap` accepts the proposal and composes `/record-decision(content, target, decision-metadata)` to write and record the . + +When invoked **independently**: + +- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. +``` + +Additional "When composed by ..." blocks (e.g. `/implement`, `/review` for `/assess-stack`'s implementation/review modes) follow the same Input/Output/Persistence shape — only the caller name, trigger, and target/ADR-vs-ADL vary. + +## Standard degradation bullet + +> If the caller cannot persist (e.g. `/record-decision` not installed), the proposal stands as a report — adoption stays unchanged. + +## What stays in the skill (the delta) + +- The exact `target` file/section and the `decision-metadata` values (`$type`, `$topic`, `$summary` template) for that domain — these are the whole point of each assess-* skill and never move out. +- Whether the decision is typically architectural or non-architectural for that domain, and the exception condition when it flips (e.g. "testing decisions are non-architectural, exception: contract testing requiring service boundaries") — this is domain judgment, not boilerplate; it stays as a Notes bullet, `/record-decision`'s own classification gate (Step 1) still runs regardless. +- Section-ownership notes (which skill owns which part of a shared file). diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/resolution-cascade.md b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/resolution-cascade.md new file mode 100644 index 00000000..7f690bee --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/resolution-cascade.md @@ -0,0 +1,34 @@ +# Resolution Cascade + +The generic priority order a skill uses to decide **how much work it still needs to do**, before running its full algorithm: an explicit argument wins over existing adoption, which wins over a fresh assessment. Three paths, always evaluated in order, each following **check → skip → act → verify**. + +## Path A — Argument Override + +1. **Check**: Is the skill's override argument (typically `$choice`) provided? +2. **Skip**: If not provided, go to Path B. +3. **Act**: Confirm the override with the developer — surface any conflict with existing adoption before accepting it. +4. **Verify**: Developer confirms. Proceed to the skill's main algorithm (skip guideline-reading/assessment). + +## Path B — Existing State Check + +Two variants, depending on the skill's nature: + +- **Decision skills** (the `assess-*` family): Path B checks whether the relevant **adoption file/section already exists and is populated**. If yes: read it, confirm it's still valid, check a corresponding decision record exists (ADR/ADL — see [record-decision-contract.md](record-decision-contract.md)), report a gap if missing, then exit — the resolution cascade **is** the idempotency mechanism for these skills (adoption already reflects the decision, so there's nothing left to assess). +- **Report/analysis skills** (e.g. an `analyze-*` skill): Path B checks whether a **recent output already exists** (report, prior analysis) instead of an adoption file. If found and not stale, confirm and exit; if stale or the developer requests it, proceed to Path C. This variant is the [idempotency convention](idempotency.md) applied at Step 1. + +1. **Check**: Does the relevant existing state (adoption section, or recent report) exist and hold? +2. **Skip**: If not, go to Path C. +3. **Act**: Present the existing state; ask whether to keep it or redo. +4. **Verify**: If kept → exit skill. If redo requested (or state is stale/missing) → proceed to Path C. + +## Path C — Full Assessment/Analysis + +1. **Act**: Proceed to the skill's main algorithm (read guidelines, evaluate, produce the proposal or report). + +## Per-skill delta (what stays in the skill, not here) + +Only these vary per skill and belong in the skill's own `### Step 1: Resolution Cascade` section, right after the pointer to this file: + +- Which adoption file/section (or which "existing output" signal) Path B checks against. +- The exact confirmation/HALT prompt wording for that domain. +- Which step number Path C proceeds to (depends on the skill's own algorithm layout). diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md new file mode 100644 index 00000000..0d00105e --- /dev/null +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md @@ -0,0 +1,21 @@ +# Way-of-Working / PM-Tool Resolution + +How any skill that needs the project's PM tool (to read or write a story/PR/epic) determines **which tool it is and how to reach it**, and how it translates board-specific state into the canonical vocabulary the corpus uses. + +## PM tool discovery + +1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) and identify the adopted PM tool (GitHub Projects, Jira, Linear, etc.) and its access method. +2. **Skip**: If found, proceed with that tool. +3. **Act**: If no PM tool is configured, **HALT**: + + > No PM tool configured in `way-of-working.md`. Configure via `/setup-pm`, or manually set the PM tool in way-of-working.md. + +4. **Verify**: PM tool identified and reachable (or the HALT above has been surfaced). + +## State resolution (macrostates) + +Skills refer to **canonical macrostates** (`Draft`, `Ready`, `In Progress`, `Review`, `Done`) — never board-specific column/label names. Resolve an item's actual board state to a macrostate via the `## State Mapping` section in way-of-working.md; if that section is omitted, canonical names are assumed (zero-configuration default, not a degradation). See [canonical-states.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/canonical-states.md) for the full resolution rule, including the **Readiness Fallback**: when a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), evaluate Definition-of-Ready criteria against the item instead of guessing from the board-state name. + +## What stays in the skill (the delta) + +Most skills only need a short pointer where they read/write the PM tool — e.g. "Read the story from the PM tool (resolution: see [way-of-working-pm-resolution.md](way-of-working-pm-resolution.md))" — because `/write-issue` is the actual PM-tool writer for creation/update flows and already implements the discovery+HALT logic above in full. A skill only needs to **restate** the full discovery+HALT block (Steps 1-4 above) if it talks to the PM tool directly rather than delegating to `/write-issue` — keep that as the delta; everything else points here. diff --git a/packages/knowledge-hub/dataset/.skills/capability/analyze-code-quality/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/analyze-code-quality/SKILL.md index 386f3447..7f1c9618 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/analyze-code-quality/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/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,7 +141,8 @@ 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." @@ -160,7 +150,7 @@ When invoked **independently**: ## 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 `/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. diff --git a/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md index c901c8a8..580cbcee 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/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. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md index 7281b5d1..acde71cf 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/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 `/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 `/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 `/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 `/bootstrap`: - **Input**: `/bootstrap` invokes during Phase 2. -- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing. -- **Persistence**: `/bootstrap` accepts the proposal and composes `/record-decision(content, target, decision-metadata)` to write the AI section and record the ADL. - -When invoked **independently**: +- **Persistence**: `/bootstrap` composes `/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 `/record-decision`, then commits. +When invoked **independently**: the human (or agent) persists the proposal by composing `/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. `/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 `/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 diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md index 8210f2ba..1eb09088 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/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 `/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 `/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 `/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 `/bootstrap`: - **Input**: `/bootstrap` invokes `/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**: `/bootstrap` accepts the proposal and composes `/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**: `/bootstrap` composes `/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 `/record-decision`, then commits. +When invoked **independently**: the human (or agent) persists the proposal by composing `/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. `/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 diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md index feafbdf2..2bf62cf9 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md @@ -30,25 +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. Check for conflicts with existing adoption. -4. **Verify**: Developer confirms. Proceed to Step 3. - -#### Path B — Adoption Exists - -1. **Check**: Does [adoption/tech/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) exist and is it populated? -2. **Skip**: If not populated or missing, go to Path C. -3. **Act**: Read current 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 `/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/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md), populated. If a corresponding decision record is missing, report the gap (this skill still writes nothing; the caller persists a backfill via `/record-decision`). +- **Path C delta**: proceed to Step 2. ### Step 2: Read Guidelines @@ -96,10 +82,12 @@ The rendered adoption content is destined for this file — the caller writes it - `target`: [adoption/tech/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) (core sections) - `decision-metadata`: `$type: architectural` (infrastructure decisions affect system structure), `$topic: infrastructure-strategy`, `$summary: "[Summary of key infrastructure choices]"` - plus the human-facing report (see Output Format) -2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/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: Infrastructure @@ -113,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 `/bootstrap`: - **Input**: `/bootstrap` invokes during Phase 2. -- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing. -- **Persistence**: `/bootstrap` accepts the proposal and composes `/record-decision(content, target, decision-metadata)` to write infrastructure.md and record the ADR. - -When invoked **independently**: +- **Persistence**: `/bootstrap` composes `/record-decision` to write infrastructure.md and record the ADR. -- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. +When invoked **independently**: the human (or agent) persists the proposal by composing `/record-decision`, then commits. ## Edge Cases @@ -131,9 +118,7 @@ When invoked **independently**: ## Graceful Degradation -- If infrastructure guidelines not found, use minimal assessment: ask developer for CI/CD and deployment preferences. -- If the caller cannot persist (e.g. `/record-decision` not installed), the proposal stands as a report — adoption stays unchanged. -- If adoption files are missing, the assessment still runs — the caller creates the file on persist via `/record-decision`. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for CI/CD and deployment 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 diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md index 9b7704b6..e0ef096f 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/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/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) exist and contain a methodology reference (e.g. "Kanban", "Scrum", or similar)? -2. **Skip**: If no methodology defined, go to Path C. -3. **Act**: Read current 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 `/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/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) containing a methodology reference (e.g. "Kanban", "Scrum"). If a corresponding decision record is missing, report the gap (this skill still writes nothing; the caller persists a backfill via `/record-decision`). +- **Path C delta**: proceed to Step 2. ### Step 2: Read Guidelines @@ -101,10 +87,12 @@ The rendered adoption content is destined for this section — the caller writes - `target`: [adoption/tech/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) (methodology section) - `decision-metadata`: `$type: non-architectural`, `$topic: methodology-choice`, `$summary: "[Methodology] adopted for development workflow"` - plus the human-facing report (see Output Format) -2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/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: Methodology @@ -118,15 +106,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 `/bootstrap`: - **Input**: `/bootstrap` invokes during Phase 2. -- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing. -- **Persistence**: `/bootstrap` accepts the proposal and composes `/record-decision(content, target, decision-metadata)` to write the methodology section and record the ADL. - -When invoked **independently**: +- **Persistence**: `/bootstrap` composes `/record-decision` to write the methodology section and record the ADL. -- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. +When invoked **independently**: the human (or agent) persists the proposal by composing `/record-decision`, then commits. ## Edge Cases @@ -136,9 +123,7 @@ When invoked **independently**: ## Graceful Degradation -- If methodology guidelines not found, use minimal assessment: ask developer for methodology preference based on team size and requirements stability. -- If the caller cannot persist (e.g. `/record-decision` not installed), the proposal stands as a report — adoption stays unchanged. -- If way-of-working.md doesn't exist, the assessment still runs — the caller creates the file on persist via `/record-decision`. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for methodology preference based on team size/requirements stability) 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 diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md index 2ad8e6e4..a1a5aece 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-observability/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/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) exist and contain a populated **observability** section? -2. **Skip**: If no observability section or empty, go to Path C. -3. **Act**: Read current observability 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 `/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/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) — populated **observability** section. If a corresponding decision record is missing, report the gap (this skill still writes nothing; the caller persists a backfill via `/record-decision`). +- **Path C delta**: proceed to Step 2. ### Step 2: Read Guidelines @@ -99,10 +85,12 @@ The rendered adoption content is destined for this section — the caller writes - `target`: [adoption/tech/infrastructure.md](../../../.pair/adoption/tech/infrastructure.md) (observability section) - `decision-metadata`: `$type: non-architectural` (observability tooling is typically a tool choice), `$topic: observability-strategy`, `$summary: "[Platform] adopted for observability with [logging approach]"` - plus the human-facing report (see Output Format) -2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/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: Observability @@ -116,15 +104,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 `/bootstrap`: - **Input**: `/bootstrap` invokes during Phase 2, after /assess-infrastructure. -- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing. -- **Persistence**: `/bootstrap` accepts the proposal and composes `/record-decision(content, target, decision-metadata)` to write the observability section and record the ADL. - -When invoked **independently**: +- **Persistence**: `/bootstrap` composes `/record-decision` to write the observability section and record the ADL. -- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. +When invoked **independently**: the human (or agent) persists the proposal by composing `/record-decision`, then commits. ## Edge Cases @@ -134,9 +121,7 @@ When invoked **independently**: ## Graceful Degradation -- If observability guidelines not found, use minimal assessment: ask developer for platform preference. -- If the caller cannot persist (e.g. `/record-decision` not installed), the proposal stands as a report — adoption stays unchanged. -- If infrastructure.md doesn't exist, the assessment still runs — the caller creates the file on persist via `/record-decision`. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for platform preference 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 diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md index d22d6d72..10998aa5 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md @@ -34,25 +34,11 @@ The rendered adoption content is destined for this section — the caller (or `/ ### 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/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) contain a PM tool configuration? -2. **Skip**: If no PM tool defined, go to Path C. -3. **Act**: Read current PM 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 `/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 a PM tool configuration in [adoption/tech/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md). If a corresponding decision record is missing, report the gap (this skill still writes nothing; the caller persists a backfill via `/record-decision`). +- **Path C delta**: proceed to Step 2. ### Step 2: Read Guidelines @@ -105,10 +91,12 @@ The rendered adoption content is destined for this section — the caller (or `/ - `target`: [adoption/tech/way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) (PM tool section) - `decision-metadata`: `$type: non-architectural`, `$topic: pm-tool-choice`, `$summary: "[Tool] adopted for project management"` - plus the human-facing report (see Output Format) -3. **Verify**: Proposal emitted. Persistence is performed by the caller via `/record-decision(content, target, decision-metadata)`, never by this skill. +3. **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) (with a `Delegated` status for the /setup-pm handoff — a legitimate per-skill variant, see that file). + ```text ASSESSMENT COMPLETE (output-only for adoption — no files written by this skill): ├── Domain: Project Management @@ -122,15 +110,14 @@ ASSESSMENT COMPLETE (output-only for adoption — no files written by this skill ## 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 `/bootstrap`: - **Input**: `/bootstrap` invokes during Phase 2 (checklist completion). May pass `$choice`. -- **Output**: If `/setup-pm` was composed, returns its output. Otherwise returns `{ content, target, decision-metadata }` plus the report — writes nothing. -- **Persistence**: when not delegated, `/bootstrap` accepts the proposal and composes `/record-decision(content, target, decision-metadata)`. - -When invoked **independently**: +- **Persistence**: if `/setup-pm` was composed, it already persisted — otherwise `/bootstrap` composes `/record-decision`. -- Full interactive flow. If `/setup-pm` is present it persists; otherwise the human (or agent) persists the proposal by composing `/record-decision`, then commits. +When invoked **independently**: if `/setup-pm` is present it persists; otherwise the human (or agent) persists the proposal by composing `/record-decision`, then commits. ## Edge Cases @@ -140,9 +127,7 @@ When invoked **independently**: ## Graceful Degradation -- If PM tool guidelines not found, use minimal assessment: ask developer for tool preference. -- If `/setup-pm` not installed, emit the proposal for the caller to persist via `/record-decision` (no tool-specific configuration). -- If the caller cannot persist (e.g. `/record-decision` not installed), the proposal stands as a report — adoption stays unchanged. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for tool preference directly; optional skill `/setup-pm` not installed → emit the proposal for the caller to persist via `/record-decision`, no tool-specific configuration) 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 diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md index 9dda6c9d..c8f55f66 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md @@ -59,41 +59,11 @@ Detect and evaluate unlisted dependencies. Used when `/review` finds a dependenc ### Step 1: Resolution Cascade -#### Path A — Argument Override (implementation or bootstrap with $choice) +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** (implementation mode): Validate compatibility: - - Parse `$choice` as `name@version`. - - Check existing [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) for conflicts: - - Version incompatibility (e.g. library needs Node 20, stack has Node 18) - - Duplicate entry (same library already listed) - - Category conflict (e.g. two ORMs) - - If conflict detected, warn developer: - - > **Compatibility issue**: `$choice` conflicts with existing stack. - > - Conflict: [description] - > - Options: (a) resolve conflict and proceed, (b) reject addition - -4. **Act** (bootstrap mode with choice): Confirm the choice and proceed to Step 3. -5. **Verify**: Choice validated. Proceed to Step 3. - -#### Path B — Adoption Exists - -1. **Check**: Does [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) exist with populated core sections? -2. **Skip**: If not populated or missing, go to Path C. -3. **Act**: Read current adoption. Present summary: - - > Tech stack already adopted. Core sections populated. - > [Summary of key technologies with versions] - -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 `/record-decision`. -6. **Verify**: Adoption and decision record consistent. Done — exit skill. - -#### Path C — Full Assessment (bootstrap mode) - -1. **Act**: Proceed to Step 2 (full assessment). +- **Path A delta** (implementation or bootstrap with `$choice`): parse `$choice` as `name@version`; in implementation mode, validate against [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) for version incompatibility, duplicate entry, or category conflict — warn and offer resolve-or-reject if found. In bootstrap mode with a choice, just confirm. Proceed to Step 3. +- **Path B delta**: adoption check is [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) with populated core sections. If a corresponding decision record is missing, report the gap (this skill still writes nothing; the caller persists a backfill via `/record-decision`). +- **Path C delta** (bootstrap mode): proceed to Step 2 (full assessment). ### Step 2: Read Guidelines (bootstrap mode only) @@ -183,7 +153,7 @@ Detect and evaluate unlisted dependencies. Used when `/review` finds a dependenc - **Implementation**: `$type: non-architectural`, `$topic: stack-add-[name]`, `$summary: "[name]@[version] added to tech stack — [rationale]"` - **Review approve**: `$type: non-architectural`, `$topic: stack-approve-[name]`, `$summary: "[name]@[version] approved during review — added to tech stack"` - plus the human-facing report (see Output Format), and the validation result (approved/rejected) for implementation/review modes -2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/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). ## Version Tracking Policy @@ -205,6 +175,8 @@ Detect and evaluate unlisted dependencies. Used when `/review` finds a dependenc ## Output Format +Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape) (with an added `Mode` line — a legitimate per-skill variant, see that file, since this skill spans the whole project lifecycle). + ```text ASSESSMENT COMPLETE (output-only — no files written): ├── Domain: Tech Stack @@ -219,27 +191,26 @@ 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 `/bootstrap`: - **Input**: `/bootstrap` invokes `/assess-stack` during Phase 2 with `$mode: bootstrap`. May pass `$choice` for pre-selected stack. -- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing. -- **Persistence**: `/bootstrap` accepts the proposal and composes `/record-decision(content, target, decision-metadata)`, then includes those changes in the next commit. +- **Persistence**: `/bootstrap` composes `/record-decision`, then includes those changes in the next commit. When composed by `/implement`: - **Input**: `/implement` detects new import/dependency → invokes `/assess-stack` with `$choice: [name@version]`, `$mode: implementation`. -- **Output**: Returns the validation result (approved/rejected) plus, when approved, `{ content, target, decision-metadata }`. +- **Output**: Returns the validation result (approved/rejected) plus, when approved, the proposal. - **Persistence**: on approval, `/implement` persists the entry via `/record-decision`. If rejected (incompatible) → `/implement` HALTs. When composed by `/review`: - **Input**: `/review` detects unlisted dependency → invokes `/assess-stack` with `$choice: [name@version]`, `$mode: review`. -- **Output**: Returns the developer decision (approve/reject) plus, when approved, `{ content, target, decision-metadata }`. +- **Output**: Returns the developer decision (approve/reject) plus, when approved, the proposal. - **Persistence**: on approval, `/review` persists via `/record-decision`. If rejected → `/review` includes as CHANGES-REQUESTED finding. -When invoked **independently**: - -- Full interactive flow. Mode auto-detected. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. +When invoked **independently**: mode auto-detected. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. ## Edge Cases @@ -252,10 +223,10 @@ When invoked **independently**: ## Graceful Degradation -- If technology guidelines are not found, use minimal assessment: ask developer for stack choices directly. -- If the caller cannot persist (e.g. `/record-decision` not installed), the proposal stands as a report — adoption stays unchanged. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for stack choices directly; adoption file missing in bootstrap mode → the skill still runs, caller creates it on persist) and [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) (persistence unavailable → proposal stands as a report) for the standard scenarios. Additional cases: + - If architecture.md doesn't exist, warn: "No architecture adopted — stack compatibility cannot be verified against architecture." -- If tech-stack.md doesn't exist (bootstrap mode), the caller creates it on persist. If implementation/review mode, HALT: "No tech stack defined — run /assess-stack in bootstrap mode first." +- If tech-stack.md doesn't exist in implementation/review mode (as opposed to bootstrap, covered above), HALT: "No tech stack defined — run /assess-stack in bootstrap mode first." ## Notes diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md index 97819f9b..c3b315f5 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md @@ -30,40 +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 with the developer: - - > Testing framework override: **$choice**. - > This will be proposed without full assessment. - > Confirm? - -4. **Check**: Does [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) already have a testing section with a different framework? - - If yes, warn: "Current testing framework is **[existing]**. Override to **$choice**?" -5. **Verify**: Developer confirms. Proceed to Step 2. - -#### Path B — Adoption Exists - -1. **Check**: Does [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) exist and contain a populated **Testing** section? -2. **Skip**: If no testing section or section is empty/template, go to Path C. -3. **Act**: Read current testing adoption. Present: - - > Testing strategy already adopted: - > - Framework: **[name vX.Y]** - > - Coverage tool: **[name vX.Y]** - > - Additional tools: **[list]** - > - > Adoption is current and valid. - -4. **Check**: Does a corresponding decision record exist? (Scan [adoption/decision-log/](../../../.pair/adoption/decision-log/) or [adoption/tech/adr/](../../../.pair/adoption/tech/adr/) for `*testing*` 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 `/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: "Testing framework override: **$choice**. This will be proposed without full assessment. Confirm?" — also warn if tech-stack.md already has a testing section with a different framework. On confirm, proceed to Step 2. +- **Path B delta**: adoption check is [adoption/tech/tech-stack.md](../../../.pair/adoption/tech/tech-stack.md) — populated **Testing** section. Decision-record check scans [adoption/decision-log/](../../../.pair/adoption/decision-log/) or [adoption/tech/adr/](../../../.pair/adoption/tech/adr/) for `*testing*` files; if missing, report the gap (this skill still writes nothing; the caller persists a backfill via `/record-decision`). +- **Path C delta**: proceed to Step 2 (full assessment mode). ### Step 2: Read Guidelines @@ -117,10 +88,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) (Testing section) - `decision-metadata`: `$type: non-architectural` (testing framework is a tooling choice), `$topic: testing-strategy`, `$summary: "[Framework] vX.Y adopted as testing framework with [coverage target]% coverage"` - plus the human-facing report (see Output Format) -2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/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: Testing @@ -134,15 +107,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 `/bootstrap`: - **Input**: `/bootstrap` invokes `/assess-testing` during Phase 2. May pass `$choice` if developer pre-selected. -- **Output**: Returns `{ content, target, decision-metadata }` plus the report. Writes nothing. -- **Persistence**: `/bootstrap` accepts the proposal and composes `/record-decision(content, target, decision-metadata)` to write the Testing section and record the ADL, then includes those changes in the next commit. - -When invoked **independently**: +- **Persistence**: `/bootstrap` composes `/record-decision` to write the Testing section and record the ADL, then includes those changes in the next commit. -- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/record-decision`, then commits. +When invoked **independently**: the human (or agent) persists the proposal by composing `/record-decision`, then commits. ## Edge Cases @@ -154,9 +126,7 @@ When invoked **independently**: ## Graceful Degradation -- If testing guidelines are not found, use minimal assessment: ask developer for framework preference based on language. -- If the caller cannot persist (e.g. `/record-decision` not installed), the proposal stands as a report — adoption stays unchanged. -- If tech-stack.md doesn't exist, the assessment still runs and produces its proposal — the caller creates the file on persist via `/record-decision`. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for framework preference based on language) 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 diff --git a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md index 1d900373..bf6d1015 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md @@ -136,15 +136,16 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → use a minimal structure directly; PM tool not accessible during state reconstruction, Step 3 → ask the developer to confirm tasks done/pending directly) for the standard scenarios. Additional cases: + - If the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md) is not found, use the minimal five-section structure directly: Story, Branch, Tasks Done, Key Decisions, Remaining Todos. - If `.pair/working/` does not exist yet, create it (and `checkpoints/` under it) on first write. - If git is not available or the branch cannot be determined, mark the Branch section `[unknown — needs confirmation]` rather than guessing. -- If the PM tool is not accessible during state reconstruction (Step 3), ask the developer to confirm tasks done/pending directly. ## Notes - This skill **writes at most one file** — `.pair/working/checkpoints/.md` — and only in write mode with `$persist=true` (default). -- **Idempotent**: re-invoking write mode updates the same file in place; it never duplicates. Re-invoking resume mode is read-only and safe to repeat. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: write mode updates the same file in place (never duplicates); resume mode is read-only and safe to repeat. - `.pair/working/` holds operational, per-project runtime state — never touched by install or update (D14). It is not part of the distributed KB defaults. - Checkpoints complement, not replace, git/PM-tool state. Even when state is reliably reconstructible from git and the PM tool (as `/implement` does today), a checkpoint adds an explicit, fast-to-read summary — most valuable across context resets and subagent handoffs, where reconstruction from scratch is expensive or impossible. - The write-free (`$persist=false`) option serves composers that own their own persistence (e.g., embedding the handoff directly into a PR body) rather than writing a separate file. diff --git a/packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md index 7e4004d9..2e651854 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md @@ -165,6 +165,6 @@ When invoked **independently**: - This skill **generates test definitions** — it does not execute tests or modify application code. - Test case IDs are stable across regenerations if the same surfaces are discovered. -- The skill is idempotent: re-running on an existing suite offers regenerate/extend/abort. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-running on an existing suite offers regenerate/extend/abort. - Generated test cases are version-agnostic by design — they work across releases without modification. - Suite maintenance (adding tests for new features) should re-invoke this skill with `extend` mode. diff --git a/packages/knowledge-hub/dataset/.skills/capability/estimate/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/estimate/SKILL.md index 4e255934..28c06ad3 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/estimate/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/estimate/SKILL.md @@ -20,7 +20,7 @@ Apply the adopted estimation methodology to size a refined user story. Reads the ### Step 1: Load Story -1. **Check**: Read the story from the PM tool (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)). +1. **Check**: Read the story from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md). 2. **Verify**: Story exists and has acceptance criteria. If not refined → **HALT**: "Story must be refined before estimation." ### Step 2: Check Existing Estimate @@ -108,14 +108,14 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → fall back to developer judgment; PM tool not accessible → ask the developer to record manually) for the standard scenarios. Additional cases: + - If [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) does not specify an estimation methodology, use the Decision Matrix from the estimation guidelines to recommend one. -- If estimation guidelines are not found, fall back to developer judgment: ask the developer to provide an estimate directly and record it. -- If the PM tool is not accessible, present the estimate and ask the developer to record it manually. - If the story has no acceptance criteria, warn: "Story lacks AC — estimation may be inaccurate. Consider refining first." ## Notes - This skill **modifies the PM tool** — it writes the estimate to the story issue. -- **Idempotent**: re-invocation on an already-estimated story confirms the existing estimate without re-doing the analysis. Re-estimation only happens on explicit developer request. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: an already-estimated story is confirmed without re-doing the analysis; re-estimation only on explicit developer request. - The estimation method should be consistent within a project. If the team switches methods, record the decision via `/record-decision`. - Estimation is a collaborative activity — the skill proposes, the developer decides. The skill never overrides developer judgment. diff --git a/packages/knowledge-hub/dataset/.skills/capability/execute-manual-tests/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/execute-manual-tests/SKILL.md index 30d01b1e..fece3d44 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/execute-manual-tests/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/execute-manual-tests/SKILL.md @@ -162,11 +162,13 @@ To maximize reliability when executed by AI agents: - **Version from artifact**: extract from the artifact itself, never from source code. - **Isolated filesystem**: `$WORKDIR` must be outside the repo to avoid workspace interference. - **Clean npm environment**: use `--no-workspaces`, ensure no `.npmrc` inheritance from parent dirs. -- **Idempotent re-run**: re-executing produces the same result without manual cleanup. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-executing produces the same result without manual cleanup. ## Graceful Degradation -- **No test suite found**: HALT with guidance to run `/design-manual-tests` first. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → use a minimal structure directly) for the standard scenarios. Additional cases: + +- **No test suite found**: HALT with guidance to run `/design-manual-tests` first (a required dependency, not optional). - **`agent-browser` not available**: Fall back to Playwright MCP. If Playwright MCP also unavailable, fall back to WebFetch/curl for HTTP checks. Mark interactive tests (search, responsive) as BLOCKED. - **No internet**: Skip tests requiring network (website, registry, auto-download). Mark as BLOCKED with reason. - **Suite-specific variable not resolvable**: Mark dependent tests as BLOCKED with the resolution hint from the suite README. diff --git a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md index f0f7cba8..4ce606bc 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md @@ -205,9 +205,10 @@ AI: GRILL SESSION COMPLETE — Mode: sync · Coverage: 6/6 · returns alignment ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (composing skill not installed → this skill still runs standalone) for the standard scenarios. Additional cases: + - If KB/codebase exploration is unavailable (no repo access), skip Step 1 (nothing marked explored), ask every aspect/topic question directly, and note in the synthesis that explore-first was skipped. - If `.pair/working/` cannot be created or written, present the handoff content inline in conversation and tell the human to save it manually. -- If the composing skill (`/brainstorm`, `/refine-story`) is not installed, grill still runs standalone — it has no required composed skills. ## Notes diff --git a/packages/knowledge-hub/dataset/.skills/capability/manage-flags/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/manage-flags/SKILL.md index 7df7296e..aa86bc64 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/manage-flags/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/manage-flags/SKILL.md @@ -124,7 +124,8 @@ When invoked **independently**: ## Graceful Degradation -- If [feature-flags.md](../../../.pair/knowledge/guidelines/technical-standards/feature-flags.md) is not found, provide framework-agnostic patterns: simple boolean flags with environment variables. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → fall back to framework-agnostic patterns: simple boolean flags with environment variables) for the standard scenarios. Additional cases: + - If no feature flag tool is configured, use code-level flags (constants, config files) rather than a flag service. - If no existing flags are found in the codebase, report empty inventory and offer to create the first flag. - If cleanup would break active code paths, warn and require explicit developer confirmation. @@ -132,7 +133,7 @@ When invoked **independently**: ## Notes - This skill **modifies files** — it creates, activates, deactivates, and removes feature flag code and configuration. -- **Idempotent**: invoking `create` on an existing flag shows its current state instead of re-creating. Invoking `activate` on an active flag confirms the state. Invoking `cleanup` always requires explicit confirmation. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: `create` on an existing flag shows its current state instead of re-creating; `activate` on an active flag confirms the state; `cleanup` always requires explicit confirmation. - **Stale flag detection**: flags inactive for more than 30 days are flagged as stale. Cleanup is recommended but not forced. - Flag naming conventions should follow the project's adopted coding standards (e.g., `SCREAMING_SNAKE_CASE` for env vars, `camelCase` for code constants). - Cleanup is the most critical lifecycle phase — leftover flags create technical debt. The `status` action helps identify cleanup candidates. diff --git a/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md index 6e857db4..0c762463 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md @@ -153,6 +153,8 @@ CONTEXT PLACEMENT COMPLETE: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (adoption files missing → warn, proceed with what's available rather than halting) for the standard scenarios. Additional cases: + - If architecture or tech-stack adoption files are missing, warn and infer boundaries from subdomains alone. - If subdomains have no `Volatility` field yet, treat volatility as unknown/Medium for the assessment and note it as provisional. - If neither a subdomain nor a bounded-context catalog exists, use the system-areas fallback (Step 2b) rather than halting. @@ -162,7 +164,7 @@ CONTEXT PLACEMENT COMPLETE: ## Notes - This skill **creates/updates adoption files** — not PM tool issues. Bounded contexts are design artifacts. -- Idempotent: re-invocation detects existing files by filename; only entries inside `$scope` are evaluated for changes. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing files by filename; only entries inside `$scope` are evaluated for changes. - The 3-dimension relationship assessment (strength, distance, volatility) is the input to the coupling-balance guideline — see `.pair/knowledge/guidelines/architecture/design-patterns/coupling-balance.md` (introduced by #209); until that guideline lands, apply the heuristics in Step 3 directly. - Contract-coupled (`contract` strength) relationships are annotated "contract tests expected" — `/design-manual-tests` and story-level validation strategies should pick up the contract/boundary test category for that relationship. - Migration: this skill was reclassified from a process skill (`process/map-contexts`) to a capability (`capability/map-contexts`) — see [skills-guide.md](../../../.pair/knowledge/skills-guide.md#migration-notes) for the rename and new invocation paths. diff --git a/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md index 1cb6e56e..70bd4e5c 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md @@ -141,6 +141,8 @@ SUBDOMAIN PLACEMENT COMPLETE: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (adoption/context inputs missing → warn, proceed with what's available rather than halting) for the standard scenarios. Additional cases: + - If initiatives are not available but PRD is, proceed with PRD-only analysis and warn. - If neither PRD nor initiatives nor an existing catalog are available, use the system-areas fallback (Step 2b) rather than halting. - If the adoption directory doesn't exist, create it. @@ -149,7 +151,7 @@ SUBDOMAIN PLACEMENT COMPLETE: ## Notes - This skill **creates/updates adoption files** — not PM tool issues. Subdomains are design artifacts. -- Idempotent: re-invocation detects existing files by filename; only entries inside `$scope` are evaluated for changes. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing files by filename; only entries inside `$scope` are evaluated for changes. - Volatility is evaluated from the business domain (classification-derived default + human override), never from commit history alone. - DDD classification and Volatility drive downstream assessments — see `/map-contexts` (relationship strength/distance/volatility) and the architecture-quality capability that consumes them. - Migration: this skill was reclassified from a process skill (`process/map-subdomains`) to a capability (`capability/map-subdomains`) — see [skills-guide.md](../../../.pair/knowledge/skills-guide.md#migration-notes) for the rename and new invocation paths. diff --git a/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md index d741a86f..6269fda2 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md @@ -180,9 +180,11 @@ When invoked **independently**: ## Graceful Degradation -- If [ADR template](../../../.pair/knowledge/guidelines/collaboration/templates/adr-template.md) is not found, use the minimal ADR structure: Status, Date, Context, Decision, Consequences, Adoption Impact. -- If [ADL template](../../../.pair/knowledge/guidelines/collaboration/templates/adl-template.md) is not found, use the minimal ADL structure: Date, Status, Context, Decision, Consequences, Adoption Impact. -- If [DDR template](../../../.pair/knowledge/guidelines/collaboration/templates/ddr-template.md) is not found, use the minimal DDR structure: Status, Date, Context, Decision, Consequences, Context Map Impact. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → use a minimal structure directly) for the standard scenarios. Additional cases (the minimal structure per decision type): + +- ADR template missing → minimal ADR structure: Status, Date, Context, Decision, Consequences, Adoption Impact. +- ADL template missing → minimal ADL structure: Date, Status, Context, Decision, Consequences, Adoption Impact. +- DDR template missing → minimal DDR structure: Status, Date, Context, Decision, Consequences, Context Map Impact. - If adoption directories don't exist, create them and warn: "Created adoption directory — this appears to be a new project." ## Notes diff --git a/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md index 87a7a44e..5e910950 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md @@ -154,16 +154,16 @@ When invoked **independently**: ## Graceful Degradation -- If quality-assurance guidelines are not found, propose minimal gates based on detected package.json scripts (test, lint, build). +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → propose minimal gates from what's detectable: detected package.json scripts — test, lint, build) and [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) (`/record-decision` not installed → warn and skip decision recording) for the standard scenarios. Additional cases: + - If tech-stack.md is not found, ask developer for tooling choices to generate appropriate gate commands. -- If `/record-decision` is not installed, warn and skip decision recording. - If no CI/CD platform is detectable, document gate commands for manual execution and skip pipeline file generation. - If the project is not JS/TS, document the shared-config-package pattern generically (see [shared-config-packages.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/shared-config-packages.md) § Non-JS / Polyglot Projects) and skip config-file generation — point to the ecosystem's equivalent shared config package. ## Notes - This skill **modifies files** — it writes to way-of-working.md, creates/updates CI/CD pipeline configuration, and provisions shared lint/format config packages + hook manager files (`.husky/` by default). -- **Idempotent**: re-invocation on an already-configured project confirms the existing configuration, including provisioned shared configs and hooks; update only on explicit developer request. Conflicting local config → ask before overwriting, never silently. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: an already-configured project (incl. provisioned shared configs and hooks) is confirmed; update only on explicit developer request. Conflicting local config → ask before overwriting, never silently. - Gate commands must be executable in the project's development environment. Verify commands exist before writing. - Custom Gate Registry format follows the table schema from [quality-gates.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-standards/quality-gates.md): Order, Gate, Command, Scope Key, Required, Description. - **Hook manager default**: husky (decision D21/Q11). An override recorded in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) wins — this skill reads it before provisioning. diff --git a/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md index cfc4d528..a006cf96 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md @@ -138,9 +138,11 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (adoption file missing → the skill still runs, creates it) for the standard scenarios. **This skill is the documented exception to the generic [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md)**: it writes `way-of-working.md` itself in Step 4, before composing `/record-decision` in Step 5 — so a missing `/record-decision` does not mean "nothing persisted," only that the ADL entry is skipped. Additional cases: + - If [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) doesn't exist, create it with PM section as initial content. Warn: "Created way-of-working.md — this appears to be a new project." - If implementation guide not found for selected tool, HALT with contribution instructions (Step 2.4). -- If `/record-decision` is not installed, warn and skip ADL recording: "Decision not recorded — /record-decision not installed. Please manually document the PM tool choice." +- If `/record-decision` is not installed, the way-of-working.md write has already succeeded (Step 4) — only the ADL entry (Step 5) is skipped. Warn: "Decision not recorded — /record-decision not installed. Please manually document the PM tool choice." ## Notes diff --git a/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md index 47ccd9c9..466ca11b 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md @@ -156,15 +156,15 @@ When invoked **independently**: ## Graceful Degradation -- If an adoption file for a given area does not exist, report that area as `NOT CONFIGURED` — do not fail. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (adoption file missing → report as `NOT CONFIGURED`, don't fail; guideline missing → check only what's derivable) for the standard scenarios. Additional cases: + - If `$scope=all` and no adoption files exist at all, report: "No adoption files found — run `/bootstrap` to establish project standards." -- If guidelines referenced by an area are not found, check only adoption-file-derived constraints for that area. - If the codebase is empty or no code changes to check, report all areas as `CONFORMANT` (nothing to violate). ## Notes - This skill is **read-only** — it inspects code and adoption files but never modifies anything. - **Detection-only contract**: the skill identifies non-conformities but never resolves them. Resolution is always delegated to the caller or the appropriate skill. -- **Idempotent**: re-invocation on conformant code immediately confirms compliance. Re-invocation on non-conformant code returns the same findings until the code is fixed. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: conformant code is confirmed immediately; non-conformant code returns the same findings until fixed. - **Scope is mandatory** to prevent accidental full scans when only a targeted check is needed. Use `all` explicitly for comprehensive checks. - Contextual checking: when invoked on a PR, only changes in the PR are checked, not the entire codebase. When invoked independently, the scope of code analysis is determined by the area. diff --git a/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md index f0c8ae54..515cc172 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md @@ -123,8 +123,8 @@ When invoked **independently**: ## Graceful Degradation -- If [definition-of-done.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-standards/definition-of-done.md) is not found, warn and check only adoption-derived criteria. -- If adoption files are missing, warn and check only universal DoD criteria. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → check only adoption-derived criteria; adoption files missing → check only universal criteria) for the standard scenarios. Additional cases: + - If `$story` is not provided, skip requirements/AC check and evaluate only universal criteria. - If specific guideline files are not found (e.g., security guidelines), skip that criterion group and report: "[Area]: SKIPPED — guidelines not found." - If /verify-quality already ran in the same session, reuse its results for code standards and testing criteria (avoid duplicate work). diff --git a/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md index 3aa8dd25..d6cdbf73 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md @@ -141,8 +141,9 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → run only what's detectable rather than failing) for the standard scenarios. Additional cases: + - If a standard gate command is not available (e.g., no test script in package.json), skip that gate and report: "Tests: SKIPPED — no test command found." -- If [quality-standards](../../../.pair/knowledge/guidelines/quality-assurance/quality-standards/README.md) directory is not found, warn and run only detectable gates (lint, type check, tests from package.json scripts). - If no quality-related scripts are found at all, report: "No quality gates detected. Configure quality gate commands in package.json or way-of-working.md." - If a custom gate command fails to execute (command not found), report as WARNING: "Gate `[name]`: SKIPPED — command not found." - If [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) is not found, skip custom gates entirely (standard gates still run). diff --git a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md index 32c29877..aa85eba2 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md @@ -191,16 +191,16 @@ This skill supports `story`, `task`, `epic`, and `initiative` types. Adding a ne ## Graceful Degradation -- If [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) is not found, HALT — PM tool is required. -- If the template file is not found, HALT — template-driven formatting is mandatory. -- If the PM tool implementation guide is not found, warn and proceed with default behavior. -- If the PM tool is not accessible (auth failure, rate limit, network), HALT with descriptive error — no fallback. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) for the standard scenarios — this skill deliberately **overrides the default degrade behavior with a HALT** for its two load-bearing dependencies: + +- PM tool not configured/accessible, or the template file missing → **HALT** (no fallback — this skill's entire job is writing to the PM tool via a template). +- If the PM tool implementation guide is not found, warn and proceed with default behavior (a genuine degrade, not a HALT). - If `way-of-working.md` has no `## State Mapping` section, canonical macrostate names are assumed for board writes — this is the zero-configuration default, not a degradation. ## Notes - This skill **modifies PM tool state** — it creates and updates issues. -- No PM tool fallback: if the adopted tool fails, the skill HALTs — re-invocation is idempotent (`$id` prevents duplicate creation). +- No PM tool fallback: if the adopted tool fails, the skill HALTs. **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): `$id` prevents duplicate creation on re-invocation. - Template = source of truth for issue body format. Changes to template structure automatically affect all future issue creation. - Labels and hierarchy linking follow the PM tool implementation guide conventions. - **Deliberate tech-debt promotion**: assess-* skills are output-only and never auto-create backlog items. When a debt or quality finding is worth scheduling, a human/agent promotes it here **deliberately** by passing `tech-debt` in `$labels` — a manual, selective act, never a 100% auto-conversion. diff --git a/packages/knowledge-hub/dataset/.skills/next/SKILL.md b/packages/knowledge-hub/dataset/.skills/next/SKILL.md index 43c428fa..cb073d12 100644 --- a/packages/knowledge-hub/dataset/.skills/next/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/next/SKILL.md @@ -150,9 +150,9 @@ Then ask: "Shall I run `/skill-name`?" ## Graceful Degradation +See [graceful degradation](../../.pair/knowledge/skill-conventions/graceful-degradation.md) (PM tool not accessible → skip Step 3, recommend from adoption files only; adoption files missing → suggest `/bootstrap` as the entry point) for the standard scenarios. Additional cases: + - If a suggested skill is not installed, tell the user which skill is needed and where to find it. -- If the PM tool is not accessible (no MCP connection, no credentials), skip Step 3 and report: "PM tool not accessible — recommendation based on adoption files only." -- If adoption files cannot be read (not installed yet), suggest `/bootstrap` as the entry point. - If way-of-working.md has no `## State Mapping` section, canonical macrostate names are assumed — this is the zero-configuration default, not a degradation. - If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 11's condition as unresolvable. diff --git a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md index 41ce62db..fd0ec189 100644 --- a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md @@ -284,7 +284,7 @@ On HALT: report the blocker clearly, propose resolution, wait for developer. ## Idempotent Re-invocation -Re-invoking `/bootstrap` on a partially completed project is safe and expected: +See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/bootstrap` on a partially completed project is safe and expected — per-phase: 1. **PRD**: detects existing populated PRD, skips Phase 0. 2. **Categorization**: detects existing ADL entry for `project-categorization`, skips Phase 1. @@ -297,16 +297,18 @@ Phase completion is detected via output file existence — never re-does complet ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill not installed → skip that phase/step with a warning, never blocks) and [record-decision contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) (`/record-decision` not installed → proposals cannot be persisted, document manually) for the standard scenarios. Additional cases (bootstrap's per-phase optional dependencies): + - **assess-\* skills not installed**: Skip assessment phase, reference guideline files directly, ask developer for manual decisions. Log: "assess-\* skills not installed — using manual assessment." -- **/specify-prd not installed**: HALT at Phase 0 if PRD is missing. Suggest creating PRD manually using how-to-01. +- **/specify-prd not installed**: HALT at Phase 0 if PRD is missing (a required dependency, not optional). Suggest creating PRD manually using how-to-01. - **/setup-pm not installed**: Skip PM configuration in Phase 4. Warn: "PM tool not configured — /setup-pm not installed." -- **/record-decision not installed**: Adoption cannot be persisted automatically — assess-\* skills are output-only and never write adoption themselves. Warn: "/record-decision not installed — assess-\* proposals cannot be persisted. Write adoption files manually from the proposals and record decisions by hand." - **Bootstrap checklist asset not found**: Use Phase 2 section questions as fallback — they cover the same areas. - **Adoption directory doesn't exist**: Create `adoption/tech/` and `adoption/decision-log/` on first write. +- **/record-decision not installed**: Adoption cannot be persisted automatically — assess-\* skills are output-only and never write adoption themselves. Warn: "/record-decision not installed — assess-\* proposals cannot be persisted. Write adoption files manually from the proposals and record decisions by hand." - **/map-subdomains or /map-contexts not installed**: Skip the corresponding step in Phase 3.5 with a warning. Domain modeling never blocks bootstrap completion. ## Notes -- The developer can stop between phases; re-invoke to resume (idempotency ensures correct state). +- The developer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). - Phase 3.5 is the only full-catalog (`$scope: all`) entry point for `/map-subdomains` and `/map-contexts` — every other caller is scoped to what it just touched. See [Callers Matrix](../../../.pair/knowledge/skills-guide.md#callers-matrix-scoped-capabilities). - Content source: how-to-02 Phases 0-4 (including domain modeling). How-to-02 retains orchestration flow, this skill has operational detail. diff --git a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md index 56737581..01fe334d 100644 --- a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md @@ -28,7 +28,7 @@ Implement a user story by processing its tasks sequentially. Each task follows a 1. **Check**: Is the user story already loaded in this session? 2. **Skip**: If yes, confirm story ID and move to Step 0.1b. -3. **Act**: Read the story from the PM tool (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)). +3. **Act**: Read the story from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md). - Understand business value and acceptance criteria. - Confirm epic context. 4. **Verify**: Story is fully loaded. If not → **HALT**. @@ -394,7 +394,7 @@ On HALT: report the blocker clearly, propose resolution, wait for developer. ## Idempotent Re-invocation -Re-invoking `/implement` on a partially completed story is safe and expected: +See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/implement` on a partially completed story is safe and expected — per-step: 1. **Branch**: detects existing branch, switches to it. 2. **Commit strategy**: if commits already exist on branch, infer strategy from history. @@ -407,16 +407,16 @@ The skill resumes from the first incomplete step — never re-does completed wor ## Graceful Degradation -- **PM tool not accessible**: Ask developer to manually provide story details and task list. -- **Missing adoption files**: Warn and proceed with guideline defaults. -- **/assess-stack not installed**: Warn on new dependency, continue without validation. -- **/verify-adoption not installed**: Warn, skip adoption compliance check. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (PM tool not accessible → ask the developer directly; adoption file missing → proceed with guideline defaults) for the standard scenarios. Additional cases: + +- **`/assess-stack` not installed**: Warn on new dependency, continue without validation. +- **`/verify-adoption` not installed**: Warn, skip adoption compliance check. - **No quality gate command**: Fall back to individual checks (lint, test, type check). ## Notes - This skill **modifies files and creates git artifacts** (branches, commits, PRs). - Task iteration is sequential — each task completes its full cycle before the next begins. -- The developer can stop between tasks; re-invoke to resume (idempotency ensures correct state). +- The developer can stop between tasks; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). - Single PR per story regardless of commit strategy. - **Squash happens at merge** (Phase 4), not before PR creation. Individual commits are preserved on the branch during review. diff --git a/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md index 9e314343..998770fa 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md @@ -143,14 +143,14 @@ EPICS COMPLETE: ## Graceful Degradation -- If `/write-issue` is not installed, warn and provide formatted epic content for manual PM tool entry. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/write-issue` not installed / PM tool not accessible → produce epic documents, ask developer to create manually) for the standard scenarios. Additional cases: + - If `/map-subdomains` is not installed, skip Step 3.5 with a warning — epic creation proceeds without domain mapping. - If bounded contexts are not defined, proceed with PRD and initiative analysis only. -- If PM tool is not accessible, produce epic documents and ask developer to create manually. ## Notes - This skill **modifies PM tool state** — creates epic issues linked to initiatives. -- Idempotent: re-invocation detects existing epics and skips them. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing epics and skips them. - Epic 0 rule: for new projects, always assess if a bootstrap/foundation epic is needed before functional epics. - Domain mapping (Step 3.5) is scoped to this run's epic breakdown — see [map-subdomains](../../capability/map-subdomains/SKILL.md). diff --git a/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md index 3a225d60..f0ce834a 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md @@ -134,12 +134,12 @@ INITIATIVES COMPLETE: ## Graceful Degradation -- If `/write-issue` is not installed, warn and provide formatted initiative content for manual PM tool entry. -- If the PM tool is not accessible, produce initiative documents and ask developer to create manually. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/write-issue` not installed / PM tool not accessible → produce initiative documents, ask developer to create manually) for the standard scenarios. Additional cases: + - If adoption files (architecture, tech-stack) are missing, proceed with PRD analysis only and warn. ## Notes - This skill **modifies PM tool state** — creates initiative issues. -- Idempotent: re-invocation detects existing initiatives by title matching and skips them. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing initiatives by title matching and skips them. - Initiative = highest-level work item. Hierarchy: initiative → epic → story → task. diff --git a/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md index 1566d186..4a442eee 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md @@ -149,13 +149,13 @@ STORIES COMPLETE: ## Graceful Degradation -- If `/write-issue` is not installed, warn and provide formatted story content for manual PM tool entry. -- If PM tool is not accessible, produce story documents and ask developer to create manually. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/write-issue` not installed / PM tool not accessible → produce story documents, ask developer to create/enter manually) for the standard scenarios. Additional cases: + - If epic documentation is sparse, proceed with available context and flag gaps. ## Notes - This skill **modifies PM tool state** — creates story issues linked to epics. -- Idempotent: re-invocation detects existing stories and skips them. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing stories and skips them. - Stories at breakdown stage are rough planning units — detailed requirements are added during `/refine-story`. - INVEST validation is mandatory — stories failing INVEST must be reworked before creation. diff --git a/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md index f45776b7..fd598406 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md @@ -157,13 +157,13 @@ TASK BREAKDOWN COMPLETE: ## Graceful Degradation -- If `/write-issue` is not installed, warn and provide the formatted Task Breakdown section for manual PM tool update. -- If the PM tool is not accessible, produce the task breakdown content and ask the developer to update manually. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/write-issue` not installed / PM tool not accessible → produce the task breakdown content, ask developer to update manually) for the standard scenarios. Additional cases: + - If adoption files (architecture, tech-stack, bounded contexts) are not found, skip technical context alignment and warn. ## Notes - This skill **modifies PM tool state** — it updates the story body with the Task Breakdown section. No separate task issues are created. -- Task-level idempotency: re-invoking on a story with partial tasks appends only missing ones to the story body. +- **Idempotent (task-level)** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-invoking on a story with partial tasks appends only missing ones to the story body. - Condensed TA removes verbose implementation detail that belongs in individual tasks (retained items: see Step 5). - Story template reference: [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md). diff --git a/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md index a18bf1e9..bd0b0e3f 100644 --- a/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /refine-story — Story Refinement -Transform a user story from rough breakdown (Todo) into a development-ready specification (Refined). Section-level idempotency: each refinement section is checked before acting — partial refinements resume from the first missing section. +Transform a user story from rough breakdown (Todo) into a development-ready specification (Refined). **Section-level idempotency** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): each refinement section is checked before acting; partial refinements resume from the first missing section. ## Composed Skills @@ -157,8 +157,8 @@ STORY REFINEMENT COMPLETE: ## Graceful Degradation -- If `/write-issue` is not installed, warn and provide the formatted story body for manual PM tool update. -- If the PM tool is not accessible, produce the refined story content and ask the developer to update manually. +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill `/write-issue` not installed / PM tool not accessible → produce the refined story content, ask developer to update manually) for the standard scenarios. Additional cases: + - If adoption files (architecture, tech-stack) are not found, skip technical analysis alignment checks and warn. - If `context-map.md` is not found, skip the domain check in Step 2 — its absence is the expected steady state, not an error. diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index 1c98f5e2..ec641925 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -49,7 +49,7 @@ CODE REVIEW STATE: 1. **Check**: Is the PR already loaded in this session? 2. **Skip**: If yes, confirm PR number and move to Step 1.2. -3. **Act**: Read PR from the PM tool (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)): +3. **Act**: Read PR from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md): - PR metadata (author, branch, target, status) - Changed files and diff - PR description and linked story @@ -360,7 +360,7 @@ On HALT: report the blocker, compose the resolution skill if available, wait for ## Idempotent Re-invocation -Re-invoking `/review` on a partially reviewed PR is safe: +See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/review` on a partially reviewed PR is safe — per-phase: 1. **PR context**: detects already-loaded PR, skips re-loading. 2. **Phases**: checks which phases completed (via session state or PR review comments). Resumes from first incomplete phase. @@ -371,12 +371,14 @@ Re-invoking `/review` on a partially reviewed PR is safe: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (optional skill not installed → degrade, never HALT; PM tool not accessible → ask the reviewer directly) for the standard scenarios. Additional cases: + - **/verify-adoption not installed**: Falls back to inline dependency checking against [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md). Warning logged. See degradation cascade (Phase 3). - **/assess-stack not installed**: Unlisted dependencies flagged as warnings for manual verification. Does NOT HALT. - **/analyze-debt not available**: Skip debt assessment, note in report. - **Story not found**: Review proceeds with PR-only validation (no AC check). Phase 6 skips parent cascade. -- **Code review template not found**: **HALT** — cannot produce review without template. -- **PM tool not accessible**: Ask reviewer to manually provide PR details. Phase 6 merge via CLI only. +- **Code review template not found**: **HALT** — cannot produce review without template (a required dependency, not optional). +- **PM tool not accessible**: Phase 6 merge via CLI only. - **Merge fails** (conflicts, branch protection): Report the failure, ask reviewer to resolve. Do not force-push or bypass protections. - **/execute-manual-tests not installed**: Skip Step 6.6. Log "Manual test validation skipped — skill not installed." Does NOT block merge. - **No manual test suite**: Skip Step 6.6. Log "No manual test suite found." Does NOT block merge. @@ -385,7 +387,7 @@ Re-invoking `/review` on a partially reviewed PR is safe: - This skill **reads code, posts review comments, and optionally merges PRs** — it does not modify source code. - Review phases are sequential — each phase builds on findings from prior phases. -- The reviewer can stop between phases; re-invoke to resume (idempotency ensures correct state). +- The reviewer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). - Output follows [code-review-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/code-review-template.md) — the template defines structure, /review fills it with findings. - HALT on missing ADR is inherited from [how-to-11](../../../.pair/knowledge/how-to/11-how-to-code-review.md) — this is a business rule, not a skill limitation. - **Parent cascade is best-effort** — if sub-issue queries fail, the skill reports which updates need manual attention. diff --git a/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md index c82a1acc..6fc66f24 100644 --- a/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md @@ -180,6 +180,8 @@ When invoked **independently**: ## Graceful Degradation +See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (reference material missing → use a minimal structure directly; adoption directory missing → the skill still runs, creates it) for the standard scenarios. Additional cases: + - If [PRD template](../../../.pair/knowledge/assets/PRD_template.md) not found, use the 13-section structure defined in Phase 1 Step 1.2 checklist as a minimal template. - If [PRD example](../../../.pair/knowledge/assets/PRD_example.md) not found, proceed without quality reference but warn: "No PRD example found — quality benchmarking unavailable." - If adoption directory doesn't exist, create `adoption/product/` and warn: "Created adoption directory — this appears to be a new project."