diff --git a/.claude/skills/pair-capability-analyze-code-quality/SKILL.md b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md index 75ac5063..c51f9cfb 100644 --- a/.claude/skills/pair-capability-analyze-code-quality/SKILL.md +++ b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md @@ -20,7 +20,7 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p ### Step 1: Resolution Cascade -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). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) check (no Path A/Argument-Override). - **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. @@ -103,7 +103,7 @@ 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). +Follows the [Report Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#report-shape). ```text CODE QUALITY REPORT: @@ -141,7 +141,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -150,7 +150,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill is **read-only / output-only** — it only inspects code and runs coverage (via existing test commands); files, adoption, and the PM tool stay untouched. A finding worth tracking is promoted deliberately to the backlog via `/pair-capability-write-issue` — always a manual, selective act. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 4171e3e3..6683f7f7 100644 --- a/.claude/skills/pair-capability-analyze-debt/SKILL.md +++ b/.claude/skills/pair-capability-analyze-debt/SKILL.md @@ -24,7 +24,7 @@ This skill is **output-only** — it composes no skill and writes no files. No a ### Step 1: Resolution Cascade -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. +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) check against a recent output rather than an adoption file. - **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. @@ -133,7 +133,7 @@ For each detected item, apply the prioritization formula: ## Output Format -Follows the [Report Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#report-shape). +Follows the [Report Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#report-shape). ```text TECH DEBT ANALYSIS (output-only — no files or issues created): @@ -171,13 +171,13 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. ## Notes -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: existing analysis for the codebase/PR (Step 1, Path B). +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 3573353c..44c95da5 100644 --- a/.claude/skills/pair-capability-assess-ai/SKILL.md +++ b/.claude/skills/pair-capability-assess-ai/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this section — the caller writes ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -92,11 +92,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -111,7 +111,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/pair-process-bootstrap`: @@ -129,7 +129,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for AI tool preferences directly) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 a888f714..0fa65262 100644 --- a/.claude/skills/pair-capability-assess-architecture/SKILL.md +++ b/.claude/skills/pair-capability-assess-architecture/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this file — the caller writes it ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -82,11 +82,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -101,7 +101,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/pair-process-bootstrap`: @@ -119,7 +119,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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-cost/SKILL.md b/.claude/skills/pair-capability-assess-cost/SKILL.md index 6a05b68d..359506c4 100644 --- a/.claude/skills/pair-capability-assess-cost/SKILL.md +++ b/.claude/skills/pair-capability-assess-cost/SKILL.md @@ -118,7 +118,7 @@ When invoked **independently** (`/pair-capability-assess-cost` on a branch or st ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment against §3.3 alone, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → n/a in `$diff` mode) for the standard scenarios. Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment against §3.3 alone, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → n/a in `$diff` mode) for the standard scenarios. Additional cases: - **cost-assessment guideline absent** (KB partially installed): assess against quality-model §3.3's inline signal list only, and note the reduced catalog in the output rather than HALTing. - **`/pair-capability-classify` not available** (independent invocation): the class is still emitted; it simply isn't folded into a compiled matrix by a caller — the developer reads the verdict directly. @@ -127,6 +127,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - **Writes nothing** — the strict output-only convention of the assess-* family (unlike `assess-security`, this skill has no report/audit mode: report/monitoring is deliberately split to a separate slice). The class is data for `/pair-capability-classify`/`/pair-process-review`, never an action this skill takes. - **Never blocks** — no merge authority; a `red` class is a signal for the caller, not a gate this skill enforces. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): a fresh class is computed every run against the current diff/story by design (signals change commit to commit); no cached verdict. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md): a fresh class is computed every run against the current diff/story by design (signals change commit to commit); no cached verdict. - **Provider-agnostic** — adding a provider is an adoption/KB change (a per-provider section in the guideline, or an adoption link), never a change to this skill (R2.13). - **D22** (1-line verdict + collapsed details): a project-level rendering decision the caller honors; this skill emits in that shape. diff --git a/.claude/skills/pair-capability-assess-infrastructure/SKILL.md b/.claude/skills/pair-capability-assess-infrastructure/SKILL.md index 845796ee..29757326 100644 --- a/.claude/skills/pair-capability-assess-infrastructure/SKILL.md +++ b/.claude/skills/pair-capability-assess-infrastructure/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this file — the caller writes it ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -82,11 +82,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -101,7 +101,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/pair-process-bootstrap`: @@ -118,7 +118,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for CI/CD and deployment preferences directly) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 7c764c6d..c579c341 100644 --- a/.claude/skills/pair-capability-assess-methodology/SKILL.md +++ b/.claude/skills/pair-capability-assess-methodology/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this section — the caller writes ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -87,11 +87,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -106,7 +106,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/pair-process-bootstrap`: @@ -123,7 +123,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for methodology preference based on team size/requirements stability) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 5c0dcf8d..00eef694 100644 --- a/.claude/skills/pair-capability-assess-observability/SKILL.md +++ b/.claude/skills/pair-capability-assess-observability/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this section — the caller writes ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -85,11 +85,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -104,7 +104,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/pair-process-bootstrap`: @@ -121,7 +121,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for platform preference directly) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 47c5e5f9..89e07daa 100644 --- a/.claude/skills/pair-capability-assess-pm/SKILL.md +++ b/.claude/skills/pair-capability-assess-pm/SKILL.md @@ -34,7 +34,7 @@ The rendered adoption content is destined for this section — the caller (or `/ ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -91,11 +91,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). +3. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). ## 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). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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): @@ -110,7 +110,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/pair-process-bootstrap`: @@ -127,7 +127,7 @@ When invoked **independently**: if `/pair-capability-setup-pm` is present it per ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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-security/SKILL.md b/.claude/skills/pair-capability-assess-security/SKILL.md index 18767250..423289da 100644 --- a/.claude/skills/pair-capability-assess-security/SKILL.md +++ b/.claude/skills/pair-capability-assess-security/SKILL.md @@ -65,7 +65,7 @@ Every rule the skill applies is resolved through the same layered set, most-spec ### Step 5: Resolution Cascade -See [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics. +See [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics. - **Path A** ($choice provided): adopt the named control set (e.g. `owasp-top10`) directly — render the `tech/security.md` proposal referencing it, skip full evaluation, confirm with the developer. Proceed to Step 8. - **Path B** (adoption check): `adoption/tech/security.md` exists with a populated project-rules section. Confirm it's still current with the developer; if its backing decision record is missing, report the gap (this skill still writes nothing to adoption — the caller backfills via `/pair-capability-record-decision`). No audit report is generated for an unchanged, confirmed ruleset ("no re-assessment", per the resolution cascade addendum). Exit. @@ -86,7 +86,7 @@ See [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-c ### Step 8: Render Project-Rules Proposal 1. **Act**: Render the `tech/security.md` content: global project security principles distilled from the audit findings (never duplicating KB or per-service/per-web-app guideline content — only the project-specific delta). -2. **Act**: Assemble the persistence tuple per [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md): +2. **Act**: Assemble the persistence tuple per [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md): - `content`: the rendered `tech/security.md` body. - `target`: `adoption/tech/security.md`. - `decision-metadata`: `$type: non-architectural`, `$topic: security-strategy-initial` (first audit) or `security-strategy-update` (subsequent), `$summary: "Project security rules adopted from audit: [key rules]"`. @@ -148,7 +148,7 @@ When invoked **independently** in audit mode: ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment, ask directly; adoption file missing → skill still runs against KB defaults; PM tool unreachable → n/a, this skill doesn't read the PM tool) for the standard scenarios. Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment, ask directly; adoption file missing → skill still runs against KB defaults; PM tool unreachable → n/a, this skill doesn't read the PM tool) for the standard scenarios. Additional cases: - **Package-scoped override (#237) not active**: load only the root `adoption/tech/security.md` (layer 4) — the package-scoped layer 5 is skipped entirely, not an error. - **`/pair-capability-map-contexts` not available** (for per-service/per-web-app boundary detection in review mode): fall back to inferring service/web-app boundaries from package structure (framework markers, `package.json` fields) rather than HALTing. @@ -157,6 +157,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - **Writes exactly one kind of file itself**: the audit report under `.pair/working/reports/security/` (Step 7) — the one exception to the `assess-*` family's usual output-only convention, justified the same way `/pair-capability-design-manual-tests` writes its own suite files: reports are operational artifacts (D14), not adoption content. Adoption content (`tech/security.md`) is never self-written — that always goes through the caller's `/pair-capability-record-decision` composition (Step 8). -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Audit mode's check: Path B (populated `tech/security.md` + backing decision record) confirms rather than re-running the full OWASP assessment. Review mode is not idempotent in that sense — a fresh verdict is computed every review, against the current diff, by design (findings can change commit to commit). +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). Audit mode's check: Path B (populated `tech/security.md` + backing decision record) confirms rather than re-running the full OWASP assessment. Review mode is not idempotent in that sense — a fresh verdict is computed every review, against the current diff, by design (findings can change commit to commit). - **Never scans for secrets**: committed-secret detection is a deterministic, LLM-free CI layer (R6.5) provisioned by `/pair-capability-setup-gates`, not an assessment this skill performs — keeping the "no LLM involved" guarantee real (D24). - **D22** (1-line verdict + collapsed findings, never a table inline): a project-level decision record, not part of this portable dataset. diff --git a/.claude/skills/pair-capability-assess-stack/SKILL.md b/.claude/skills/pair-capability-assess-stack/SKILL.md index 8cf0f375..4310724d 100644 --- a/.claude/skills/pair-capability-assess-stack/SKILL.md +++ b/.claude/skills/pair-capability-assess-stack/SKILL.md @@ -58,7 +58,7 @@ Detect and evaluate unlisted dependencies. Used when `/pair-process-review` find ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -152,7 +152,7 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - **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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). ## Version Tracking Policy @@ -174,7 +174,7 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- ## 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). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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): @@ -190,7 +190,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/pair-process-bootstrap`: @@ -222,7 +222,7 @@ When invoked **independently**: mode auto-detected. The skill returns the propos ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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 in implementation/review mode (as opposed to bootstrap, covered above), HALT: "No tech stack defined — run /pair-capability-assess-stack in bootstrap mode first." diff --git a/.claude/skills/pair-capability-assess-testing/SKILL.md b/.claude/skills/pair-capability-assess-testing/SKILL.md index ece31a58..bf7f6310 100644 --- a/.claude/skills/pair-capability-assess-testing/SKILL.md +++ b/.claude/skills/pair-capability-assess-testing/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this section — the caller writes ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -88,11 +88,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/pair-capability-record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -107,7 +107,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/pair-process-bootstrap`: @@ -126,7 +126,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for framework preference based on language) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 39a1ce94..56a28590 100644 --- a/.claude/skills/pair-capability-checkpoint/SKILL.md +++ b/.claude/skills/pair-capability-checkpoint/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /pair-capability-checkpoint — Resumable Progress State -Write and resume a self-contained progress checkpoint so a fresh session (or a subagent) can continue a story exactly where the previous one stopped. Follows the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)) — five sections: story, branch, tasks done, key decisions, remaining todos. +Write and resume a self-contained progress checkpoint so a fresh session (or a subagent) can continue a story exactly where the previous one stopped. Follows the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)) — five sections: story, branch, tasks done, key decisions, remaining todos. ## Arguments @@ -179,7 +179,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -188,7 +188,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **writes at most one file** — `.pair/working/checkpoints/.md` — and only in write mode with `$persist=true` (default). -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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-classify/SKILL.md b/.claude/skills/pair-capability-classify/SKILL.md index 5d5b409e..40394fd7 100644 --- a/.claude/skills/pair-capability-classify/SKILL.md +++ b/.claude/skills/pair-capability-classify/SKILL.md @@ -170,7 +170,7 @@ Review raw max = red (Change/diff risk, Security relevance), so `max(red, yellow ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal run, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → matrix returned to caller, tagging deferred). Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → minimal run, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → matrix returned to caller, tagging deferred). Additional cases: - **`/pair-capability-assess-security` not available** (review): fall back to the path-heuristic security relevance (quality-model §3.1) instead of the verdict; note the fallback. - **`/assess-coupling` not installed / no DDD artifacts**: coupling dimension "not assessed" (never a HALT). @@ -184,4 +184,4 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - **Reading budget** (D22): the body/report output is 1 line + `
`, never an inline table. - **Writes two kinds of thing itself**: the matrix into the card/PR body (Step 4) and — only on a confirmed first-run proposal — the `## Tag Projection` registry section in `tech/risk-matrix.md` (Step 5, the quality-model §5 self-write precedent, mirroring `/pair-capability-verify-quality`'s Custom Gate Registry). Adoption **decision** content is never self-written — that routes through `/pair-capability-record-decision`; the Tag Projection section is config-registry state, not a decision record. - **No eligibility tag**: automation eligibility is an adoption-declared filter over classification tags (`risk:green`, …), not a special tag — `/pair-next` consumes it generically (quality-model §5, D18). -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): re-running on an already-classified card recomputes the same matrix; a declared or opted-out Tag Projection is never re-proposed. Review re-runs recompute against the current diff (a raise can happen commit-to-commit; a lower never can). +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md): re-running on an already-classified card recomputes the same matrix; a declared or opted-out Tag Projection is never re-proposed. Review re-runs recompute against the current diff (a raise can happen commit-to-commit; a lower never can). diff --git a/.claude/skills/pair-capability-design-manual-tests/SKILL.md b/.claude/skills/pair-capability-design-manual-tests/SKILL.md index 601ec543..15802809 100644 --- a/.claude/skills/pair-capability-design-manual-tests/SKILL.md +++ b/.claude/skills/pair-capability-design-manual-tests/SKILL.md @@ -9,7 +9,7 @@ author: Foomakers Analyze a project's released artifacts, deployment targets, and user-facing surfaces to generate a complete manual test suite. Produces critical path files (`CP*.md`) and a suite `README.md` in the test suite directory. -Each test case follows the [manual-test-case-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-case-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)). Design principles: [manual-testing.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-testing.md); organizational context: [manual-verification.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-verification.md). +Each test case follows the [manual-test-case-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-case-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)). Design principles: [manual-testing.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-testing.md); organizational context: [manual-verification.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-verification.md). ## Arguments @@ -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. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-running on an existing suite offers regenerate/extend/abort. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 3bd3c414..2b08dabd 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 — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md). +1. **Check**: Read the story from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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,7 +108,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 the story has no acceptance criteria, warn: "Story lacks AC — estimation may be inaccurate. Consider refining first." @@ -116,6 +116,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **modifies the PM tool** — it writes the estimate to the story issue. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 7aa84531..a951323c 100644 --- a/.claude/skills/pair-capability-execute-manual-tests/SKILL.md +++ b/.claude/skills/pair-capability-execute-manual-tests/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /pair-capability-execute-manual-tests — Manual Test Suite Executor -Execute a manual test suite against released or deployed artifacts (website, CLI packages, registries). Produces a structured report following the [manual-test-report-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-report-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)). +Execute a manual test suite against released or deployed artifacts (website, CLI packages, registries). Produces a structured report following the [manual-test-report-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-report-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)). Reads test case files from the project's manual test suite directory; each follows the [manual-test-case-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-case-template.md). Organizational context (who, when, which areas): [manual-verification.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-verification.md); test case design principles: [manual-testing.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-testing.md). @@ -162,11 +162,11 @@ 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** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-executing produces the same result without manual cleanup. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). This skill's check: re-executing produces the same result without manual cleanup. ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → use a minimal structure directly) for the standard scenarios. Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. diff --git a/.claude/skills/pair-capability-grill/SKILL.md b/.claude/skills/pair-capability-grill/SKILL.md index c3d2e9c6..b6f32e2e 100644 --- a/.claude/skills/pair-capability-grill/SKILL.md +++ b/.claude/skills/pair-capability-grill/SKILL.md @@ -92,7 +92,7 @@ Systematic AI↔human alignment on a specific story, covering all six aspects of 1. **Act**: Compile recorded answers, explored facts (with source), and flagged assumptions: - `interview` → raw requirements blob (topic, findings per sub-question, open items, assumptions). - - `sync` → alignment synthesis mapped to the six [Sync Coverage Checklist](#sync-coverage-checklist) aspects, ready to drop into the matching [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)) sections. + - `sync` → alignment synthesis mapped to the six [Sync Coverage Checklist](#sync-coverage-checklist) aspects, ready to drop into the matching [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)) sections. 2. **Verify**: Synthesis accounts for every answered/explored/assumed item — nothing silently dropped. ### Step 6: Return — Never Write @@ -205,7 +205,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. diff --git a/.claude/skills/pair-capability-manage-flags/SKILL.md b/.claude/skills/pair-capability-manage-flags/SKILL.md index f5c146e3..1a957ff4 100644 --- a/.claude/skills/pair-capability-manage-flags/SKILL.md +++ b/.claude/skills/pair-capability-manage-flags/SKILL.md @@ -124,7 +124,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -133,7 +133,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **modifies files** — it creates, activates, deactivates, and removes feature flag code and configuration. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 dee59713..263b88de 100644 --- a/.claude/skills/pair-capability-map-contexts/SKILL.md +++ b/.claude/skills/pair-capability-map-contexts/SKILL.md @@ -115,7 +115,7 @@ For each approved context in scope: 1. **Check**: Does this context already exist as a file? 2. **Act**: If exists and no conflict was raised → leave untouched; pre-existing relationships without the 3-dimension assessment remain valid as-is (no forced migration — assessed the next time that relationship falls inside a `$scope`). -3. **Act**: If new, or an approved delta applies → create/update the context file following [bounded-context-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/bounded-context-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: If new, or an approved delta applies → create/update the context file following [bounded-context-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/bounded-context-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Fill all template sections: Type, Subdomains Covered, Business Scope, Relationships (with the 3-dimension assessment per relationship), Integration Patterns, Data Ownership, Team Alignment, Ubiquitous Language, Quality Attributes, Encapsulated Knowledge, Change Vectors. - File path: `adoption/tech/boundedcontext/[kebab-case-name].md` 4. **Verify**: File created/updated and parseable. Entries outside `$scope` are untouched. @@ -153,7 +153,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -164,7 +164,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **creates/updates adoption files** — not PM tool issues. Bounded contexts are design artifacts. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 (`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/.claude/skills/pair-capability-map-subdomains/SKILL.md b/.claude/skills/pair-capability-map-subdomains/SKILL.md index 7b71f1aa..803b0849 100644 --- a/.claude/skills/pair-capability-map-subdomains/SKILL.md +++ b/.claude/skills/pair-capability-map-subdomains/SKILL.md @@ -104,7 +104,7 @@ For each approved subdomain in scope: 1. **Check**: Does this subdomain already exist as a file? 2. **Act**: If exists and no conflict was raised → leave untouched; pre-existing entries without a `Volatility` field remain valid as-is (no forced migration — the field is added the next time this entry falls inside a `$scope`). -3. **Act**: If new, or an approved delta applies → create/update the subdomain file following [subdomain-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/subdomain-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: If new, or an approved delta applies → create/update the subdomain file following [subdomain-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/subdomain-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Fill all template sections: Classification, Volatility, Business Purpose, Key Capabilities, Strategic Importance, Complexity Assessment, Data Ownership, Dependencies, Team Recommendations, Implementation Priority. - File path: `adoption/product/subdomain/[kebab-case-name].md` 4. **Verify**: File created/updated and parseable. Entries outside `$scope` are untouched. @@ -141,7 +141,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -151,7 +151,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **creates/updates adoption files** — not PM tool issues. Subdomains are design artifacts. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 (`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/.claude/skills/pair-capability-publish-pr/SKILL.md b/.claude/skills/pair-capability-publish-pr/SKILL.md index 93079fd5..69553108 100644 --- a/.claude/skills/pair-capability-publish-pr/SKILL.md +++ b/.claude/skills/pair-capability-publish-pr/SKILL.md @@ -67,7 +67,7 @@ Each phase follows the **check → skip → act → verify** pattern. Phases run ### Phase 3: Compose the PR Body (AC3) -1. **Act**: Read the [pr-template](../../../.pair/knowledge/guidelines/collaboration/templates/pr-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md); the same resolution applies to the commit and branch templates referenced above). Fill the always-applicable sections from the handoff/story: +1. **Act**: Read the [pr-template](../../../.pair/knowledge/guidelines/collaboration/templates/pr-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md); the same resolution applies to the commit and branch templates referenced above). Fill the always-applicable sections from the handoff/story: - **Title**: `[#] : ` (`` from commit-format / story type). - **Summary** (What Changed + Why) from the story statement and the handoff's decisions. - **Story Context**: link the story issue and list AC coverage. @@ -130,7 +130,7 @@ On HALT: report the blocker, propose resolution, make no PR side effects. ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → minimal structure; PM tool inaccessible → do the PR, warn on the board step) for the standard scenarios. Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline/template missing → minimal structure; PM tool inaccessible → do the PR, warn on the board step) for the standard scenarios. Additional cases: - **No `## Merge Strategy` section**: default to `squash` + the commit template, base `main` — the zero-configuration default, not a degradation (AC2). Consistent with the merge consumers, which also default to `squash`. - **No `code-host` declared**: code host = PM tool (single-tool; AC4 still satisfied in the degraded shape). @@ -141,7 +141,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **creates git-host artifacts** (a pushed branch, one PR) and updates board state — it does not modify source files and never merges. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invocation detects the existing PR and updates it in place; re-runs the gate (fast if already green); re-parses the handoff. Never a duplicate PR. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). Re-invocation detects the existing PR and updates it in place; re-runs the gate (fast if already green); re-parses the handoff. Never a duplicate PR. - Tag propagation is a **copy**; the authoritative classification is (re)done in `/pair-process-review` (G6). - The gate here is a local pre-flight only — CI remains authoritative (#210). - The handoff/checkpoint is the input contract (see the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md)); it is consumed here, never loaded as ambient context elsewhere. diff --git a/.claude/skills/pair-capability-record-decision/SKILL.md b/.claude/skills/pair-capability-record-decision/SKILL.md index f69597e0..588b0622 100644 --- a/.claude/skills/pair-capability-record-decision/SKILL.md +++ b/.claude/skills/pair-capability-record-decision/SKILL.md @@ -88,7 +88,7 @@ A domain decision only becomes a DDR if it meets **all three** criteria. This is 1. **Check**: Does [adoption/tech/adr/](../../../.pair/adoption/tech/adr) directory exist? 2. **Act**: If not, create it. 3. **Check**: Determine the next sequence number — scan existing `adr-NNN-*.md` files, take the highest `NNN`, increment by 1 (zero-padded to 3 digits). If none exist, start at `001`. -4. **Act**: Create (or update) the ADR file at [adoption/tech/adr/](../../../.pair/adoption/tech/adr)`adr-NNN-.md` following the standalone [ADR template](../../../.pair/knowledge/guidelines/collaboration/templates/adr-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md); the same applies to the ADL, DDR, and analysis-log templates below). Fill in all sections: Status, Date, Context, Options Considered, Decision, Consequences, and Adoption Impact. +4. **Act**: Create (or update) the ADR file at [adoption/tech/adr/](../../../.pair/adoption/tech/adr)`adr-NNN-.md` following the standalone [ADR template](../../../.pair/knowledge/guidelines/collaboration/templates/adr-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md); the same applies to the ADL, DDR, and analysis-log templates below). Fill in all sections: Status, Date, Context, Options Considered, Decision, Consequences, and Adoption Impact. 5. **Verify**: ADR file exists with complete content following the template structure, and sequential numbering is unbroken. #### If `non-architectural` → ADL: @@ -236,7 +236,7 @@ When invoked **independently**: ## Graceful Degradation -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): +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. diff --git a/.claude/skills/pair-capability-setup-gates/SKILL.md b/.claude/skills/pair-capability-setup-gates/SKILL.md index f22c6176..f8c75e23 100644 --- a/.claude/skills/pair-capability-setup-gates/SKILL.md +++ b/.claude/skills/pair-capability-setup-gates/SKILL.md @@ -89,7 +89,7 @@ Configure CI/CD quality gates for the project. Reads quality assurance guideline > > Accept this configuration? -3. **Act — tiering opt-in** (per the [guided/quick setup convention](../../../.pair/knowledge/skill-conventions/guided-quick-setup.md), default **No**): the CI pipeline mode is one input resolved like any other — full-suite (default) vs risk-tier-scoped (opt-in). +3. **Act — tiering opt-in** (per the [guided/quick setup convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/guided-quick-setup.md), default **No**): the CI pipeline mode is one input resolved like any other — full-suite (default) vs risk-tier-scoped (opt-in). - **Guided mode** (interactive/TTY) — ask **one** question, pre-filled with the default: > Enable risk-tier-scoped pre-merge checks? This runs *lighter* checks on lower-risk PRs (a 🟢 PR skips integration/E2E) instead of the full suite on every PR — faster, but with less verification on low-risk changes. **[default: No — run the full suite on every PR]** @@ -174,7 +174,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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 no CI/CD platform is detectable, document gate commands for manual execution and skip pipeline file generation. @@ -186,7 +186,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - **Full checks are the default; risk-tier reduction is opt-in** (ADL 2026-07-20): unless the project sets `Pre-merge tiering: enabled` in way-of-working.md (Step 3.3 opt-in), the generated pipeline runs the **full suite on every PR** — the safe, pre-tiering behavior. Tiering only *reduces* checks on lower-risk PRs, so it must be enabled explicitly. - **When tiering is enabled, the generated pipeline reads classification tags only, never classifies** (D18): tier criteria live in [quality-model.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-model.md) §3/§4; the pipeline is the deterministic Automation layer that projects the matrix from the PR's `risk:*` tag. Untagged ⇒ 🔴 (fail-safe). See [tier-aware-pipeline.md](../../../.pair/knowledge/guidelines/infrastructure/cicd-strategy/tier-aware-pipeline.md). - **Secret scanning is CI config, not a judgment call** (D24, anti-complexity): this skill provisions the job mechanically; it never evaluates whether a diff contains a secret itself — that is gitleaks' (or the adopted scanner's) job at runtime, with no LLM in the loop. `/pair-capability-assess-security` never re-implements this — see that skill's own Notes. -- **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 is always resolved by asking first (see Edge Cases above). +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 is always resolved by asking first (see Edge Cases above). - 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 f05818fc..65324770 100644 --- a/.claude/skills/pair-capability-setup-pm/SKILL.md +++ b/.claude/skills/pair-capability-setup-pm/SKILL.md @@ -138,7 +138,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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). diff --git a/.claude/skills/pair-capability-verify-adoption/SKILL.md b/.claude/skills/pair-capability-verify-adoption/SKILL.md index dee7467a..9b715f93 100644 --- a/.claude/skills/pair-capability-verify-adoption/SKILL.md +++ b/.claude/skills/pair-capability-verify-adoption/SKILL.md @@ -156,7 +156,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 the codebase is empty or no code changes to check, report all areas as `CONFORMANT` (nothing to violate). @@ -165,6 +165,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - 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** — 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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 5872950f..fcc3646b 100644 --- a/.claude/skills/pair-capability-verify-done/SKILL.md +++ b/.claude/skills/pair-capability-verify-done/SKILL.md @@ -140,7 +140,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 the canonical [definition-of-ready-and-done.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/definition-of-ready-and-done.md) is not found, fall back to the extended `definition-of-done.md` checklist alone (never an empty checklist). diff --git a/.claude/skills/pair-capability-verify-quality/SKILL.md b/.claude/skills/pair-capability-verify-quality/SKILL.md index 37dede58..88be28bb 100644 --- a/.claude/skills/pair-capability-verify-quality/SKILL.md +++ b/.claude/skills/pair-capability-verify-quality/SKILL.md @@ -139,7 +139,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 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." diff --git a/.claude/skills/pair-capability-write-issue/SKILL.md b/.claude/skills/pair-capability-write-issue/SKILL.md index 4e097eac..39fcba25 100644 --- a/.claude/skills/pair-capability-write-issue/SKILL.md +++ b/.claude/skills/pair-capability-write-issue/SKILL.md @@ -44,7 +44,7 @@ Create or update issues in the adopted PM tool. Template-driven: reads the type- ### Step 3: Load Template -1. **Check**: Resolve the template path for `$type` **override-first** — see [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md) (adoption `.pair/adoption/tech/templates/-template.md` wins over the KB default below): +1. **Check**: Resolve the template path for `$type` **override-first** — see [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md) (adoption `.pair/adoption/tech/templates/-template.md` wins over the KB default below): - `story` → [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) - `task` → [task-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/task-template.md) - `epic` → [epic-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/epic-template.md) @@ -190,12 +190,12 @@ When composed by `/pair-process-plan-initiatives`: When composed by `/pair-process-plan-epics`: -- **Input**: `/pair-process-plan-epics` invokes `/pair-capability-write-issue` with `$type: epic`, `$content` containing the epic data, and `$parent` linking to the parent initiative. For an `EXTEND` triage outcome (see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)), it instead passes `$id` of the matched epic and `$content` as the matched epic's current full body with the additional scope already merged in by the caller — `/pair-capability-write-issue` overwrites the body as-is, it does not merge. +- **Input**: `/pair-process-plan-epics` invokes `/pair-capability-write-issue` with `$type: epic`, `$content` containing the epic data, and `$parent` linking to the parent initiative. For an `EXTEND` triage outcome (see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)), it instead passes `$id` of the matched epic and `$content` as the matched epic's current full body with the additional scope already merged in by the caller — `/pair-capability-write-issue` overwrites the body as-is, it does not merge. - **Output**: Returns the issue identifier. `/pair-process-plan-epics` uses it for linking stories. When composed by `/pair-process-plan-stories`: -- **Input**: `/pair-process-plan-stories` invokes `/pair-capability-write-issue` with `$type: story`, `$content` containing the story data, and `$parent` linking to the parent epic. For an `EXTEND` triage outcome (see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)), it instead passes `$id` of the matched story and `$content` as the matched story's current full body with the additional scope already merged in by the caller — `/pair-capability-write-issue` overwrites the body as-is, it does not merge. +- **Input**: `/pair-process-plan-stories` invokes `/pair-capability-write-issue` with `$type: story`, `$content` containing the story data, and `$parent` linking to the parent epic. For an `EXTEND` triage outcome (see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)), it instead passes `$id` of the matched story and `$content` as the matched story's current full body with the additional scope already merged in by the caller — `/pair-capability-write-issue` overwrites the body as-is, it does not merge. - **Output**: Returns the issue identifier. `/pair-process-plan-stories` uses it for status tracking. When invoked **independently**: @@ -220,7 +220,7 @@ This skill supports `story`, `task`, `epic`, and `initiative` types. Adding a ne ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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). @@ -229,7 +229,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **modifies PM tool state** — it creates and updates issues. -- 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. +- No PM tool fallback: if the adopted tool fails, the skill HALTs. **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 5a04c88d..f96282c5 100644 --- a/.claude/skills/pair-next/SKILL.md +++ b/.claude/skills/pair-next/SKILL.md @@ -206,7 +206,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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: - **Argument edge cases** (see Step 0): `--root` not found → HALT, no action; `--root` resolves to a Done issue → report and exit; `--filter` (or the subtree) matches nothing → report `no matching issues` and exit cleanly (an empty result is not an error). - If a suggested skill is not installed, tell the user which skill is needed and where to find it. diff --git a/.claude/skills/pair-process-bootstrap/SKILL.md b/.claude/skills/pair-process-bootstrap/SKILL.md index de1fdaaf..021c7cb5 100644 --- a/.claude/skills/pair-process-bootstrap/SKILL.md +++ b/.claude/skills/pair-process-bootstrap/SKILL.md @@ -253,7 +253,7 @@ On HALT: report the blocker clearly, propose resolution, wait for developer. ## Idempotent Re-invocation -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: +See [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -266,7 +266,7 @@ 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): +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (optional skill not installed → skip that phase/step with a warning, never blocks) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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." - **/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. @@ -278,6 +278,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes -- The developer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). +- The developer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 da7c2751..48621db9 100644 --- a/.claude/skills/pair-process-implement/SKILL.md +++ b/.claude/skills/pair-process-implement/SKILL.md @@ -53,7 +53,7 @@ The opening phase re-reads the checkpoint so an interrupted story resumes exactl 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 — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md). +3. **Act**: Read the story from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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**. @@ -233,7 +233,7 @@ Follow the TDD discipline rules strictly, and the [Design Rules](../../../.pair/ **This confirmation is required for EVERY task** — commit-per-task exists precisely to give the developer a checkpoint between tasks. 4. **Verify**: Developer confirms. If changes needed → apply changes, re-run quality (Step 2.7), ask again. -5. **Act**: Stage and commit following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +5. **Act**: Stage and commit following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): ```text [#] : @@ -352,7 +352,7 @@ On HALT: report the blocker clearly, propose resolution, wait for developer. ## Idempotent Re-invocation -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: +See [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). Re-invoking `/pair-process-implement` on a partially completed story is safe and expected — per-step: 1. **Checkpoint**: the opening-phase resume probe (Step 0.0) reads the checkpoint and jumps to the first pending task — never repeating completed tasks. When `/pair-capability-checkpoint` is absent, the git+PM resume below applies. 2. **Branch**: detects existing branch, switches to it. @@ -366,7 +366,7 @@ The skill resumes from the first incomplete step — never re-does completed wor ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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: - **Subagent spawning unavailable**: take the degraded inline path (Step 3.3) — checkpoint still written, `/pair-capability-publish-pr` composed inline, degradation noted in the output. Never skip the checkpoint/PR split. - **`/pair-capability-checkpoint` not installed**: skip the resume probe and the write step; resume from git+PM state (Idempotent Re-invocation) and synthesize the handoff inline for `/pair-capability-publish-pr`. @@ -380,6 +380,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - This skill **modifies files and creates git artifacts** (branches, commits) and **writes the checkpoint**. The PR itself is created/updated by the composed `/pair-capability-publish-pr` (in the subagent, or inline when degraded) — implement never re-implements PR creation. - The **subagent's prompt is the handoff only** — the checkpoint, nothing from this session. Anonymous, no named role (mechanical isolation, D23); a skill cannot `/clear` its own context (D7), so the subagent provides the clean-context reset. - Task iteration is sequential — each task completes its full cycle before the next begins. -- The developer can stop between tasks; re-invoke to resume — the opening-phase resume probe (Step 0.0) reads the checkpoint (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). +- The developer can stop between tasks; re-invoke to resume — the opening-phase resume probe (Step 0.0) reads the checkpoint (see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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-implement/post-review-merge.md b/.claude/skills/pair-process-implement/post-review-merge.md index d8e2bbce..5b596a0f 100644 --- a/.claude/skills/pair-process-implement/post-review-merge.md +++ b/.claude/skills/pair-process-implement/post-review-merge.md @@ -12,7 +12,7 @@ Disclosed from [SKILL.md](./SKILL.md) Phase 4 — only reached when `/pair-proce 1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) for merge strategy (squash, merge, rebase). 2. **Act**: Draft the final commit message: - - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)). + - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)). - **If merge or rebase**: use the default merge/rebase message. 3. **Act** (BLOCKING): Present the commit message to the developer for confirmation: diff --git a/.claude/skills/pair-process-plan-epics/SKILL.md b/.claude/skills/pair-process-plan-epics/SKILL.md index 70fb12c9..acc6df30 100644 --- a/.claude/skills/pair-process-plan-epics/SKILL.md +++ b/.claude/skills/pair-process-plan-epics/SKILL.md @@ -52,7 +52,7 @@ Transform strategic initiatives into comprehensive epic breakdowns. Each epic de ### Step 2: Build Existing Epic Registry 1. **Check**: Query PM tool for existing epic issues linked to the selected initiative — **including closed/Done items** (the closed-item triage rule in Step 3 depends on them being in the registry; many PM-tool queries default to open-only). -2. **Act**: Build a registry of existing epics, keyed for matching (idempotency key — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)): +2. **Act**: Build a registry of existing epics, keyed for matching (idempotency key — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)): ```text EXISTING EPICS: @@ -74,7 +74,7 @@ Transform strategic initiatives into comprehensive epic breakdowns. Each epic de - **Value-driven grouping**: natural feature groupings following user workflows. - **Sequential dependencies**: foundation-first, user journey progression. - **Duration sizing**: 2-4 sprints per epic with clear completion criteria. -3. **Act**: Triage each candidate epic against the Step 2 registry — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md) for the matching shape (idempotency key, EXTEND-vs-CREATE threshold, ambiguous-match and closed-item handling). **This skill's parent scope**: the selected initiative. First, check each candidate's idempotency key against the registry: an exact match to an existing **open** epic is `ALREADY EXISTS #ID` (skip) — per to-issues-triage.md's Skip step, not a triage decision. For every remaining candidate, classify `EXTEND #ID` or `CREATE` — or, if ambiguous (per to-issues-triage.md), present it as a question with a recommendation instead of silently picking one side. Present the triage proposal to developer: +3. **Act**: Triage each candidate epic against the Step 2 registry — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md) for the matching shape (idempotency key, EXTEND-vs-CREATE threshold, ambiguous-match and closed-item handling). **This skill's parent scope**: the selected initiative. First, check each candidate's idempotency key against the registry: an exact match to an existing **open** epic is `ALREADY EXISTS #ID` (skip) — per to-issues-triage.md's Skip step, not a triage decision. For every remaining candidate, classify `EXTEND #ID` or `CREATE` — or, if ambiguous (per to-issues-triage.md), present it as a question with a recommendation instead of silently picking one side. Present the triage proposal to developer: > Epic breakdown for Initiative `#[ID]: [Title]`: > @@ -103,7 +103,7 @@ Process epics sequentially (Epic 0 first if needed), per its Step 3 proposal: > Epic `[Title]` already exists (#ID). Skipping. -3. **Act**: Draft the epic following [epic-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/epic-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: Draft the epic following [epic-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/epic-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Fill template sections: Epic Statement, Business Value, Solution Overview, Epic Breakdown, Technical Considerations. - Present to developer for validation. 4. **Act**: Compose `/pair-capability-write-issue` per the confirmed proposal: @@ -142,7 +142,7 @@ EPICS COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -150,6 +150,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **modifies PM tool state** — creates and extends epic issues linked to initiatives. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md) and [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md). This skill's check: exact idempotency-key match is proposed `ALREADY EXISTS #ID` (skip) at triage time, before any write (Step 3) — Step 4 only executes the confirmed proposal; substantial-overlap match proposes EXTEND instead of a duplicate CREATE (Step 3) — re-running the same candidate tree never duplicates. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) and [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md). This skill's check: exact idempotency-key match is proposed `ALREADY EXISTS #ID` (skip) at triage time, before any write (Step 3) — Step 4 only executes the confirmed proposal; substantial-overlap match proposes EXTEND instead of a duplicate CREATE (Step 3) — re-running the same candidate tree never duplicates. - 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](../../../.skills/capability/map-subdomains/SKILL.md). diff --git a/.claude/skills/pair-process-plan-initiatives/SKILL.md b/.claude/skills/pair-process-plan-initiatives/SKILL.md index 4ef4d24d..64f67eeb 100644 --- a/.claude/skills/pair-process-plan-initiatives/SKILL.md +++ b/.claude/skills/pair-process-plan-initiatives/SKILL.md @@ -90,7 +90,7 @@ Process initiatives by priority (P0 → P1 → P2). For each initiative: > Initiative `[Title]` already exists (#ID). Skipping. -3. **Act**: Draft the initiative following the [initiative-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/initiative-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: Draft the initiative following the [initiative-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/initiative-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Fill template sections with PRD-derived content. - Include business rationale, scope, success metrics, risk assessment, timeline. - Present to developer for validation. @@ -134,12 +134,12 @@ INITIATIVES COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing initiatives by title matching and skips them. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 ed29c475..97e7fbed 100644 --- a/.claude/skills/pair-process-plan-stories/SKILL.md +++ b/.claude/skills/pair-process-plan-stories/SKILL.md @@ -55,7 +55,7 @@ Transform epics into user stories through vertical slicing, INVEST validation, a ### Step 2: Build Existing Story Registry 1. **Check**: Query PM tool for existing story issues linked to the selected epic — **including closed/Done items** (the closed-item triage rule in Step 3 depends on them being in the registry; many PM-tool queries default to open-only). -2. **Act**: Build a registry of existing stories, keyed for matching (idempotency key — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)): +2. **Act**: Build a registry of existing stories, keyed for matching (idempotency key — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)): ```text EXISTING STORIES: @@ -72,8 +72,8 @@ Transform epics into user stories through vertical slicing, INVEST validation, a - **CRUD operations**: create, read, update, delete patterns. - **Business rules**: different scenarios and conditions. - **User roles**: admin, member, guest variations. -2. **Act**: Apply vertical slicing — every story must deliver end-to-end user value with visible UI manifestation. This rule governs CREATE candidates only — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)'s per-skill-delta note. -3. **Act**: Triage each candidate story against the Step 2 registry — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md) for the matching shape (idempotency key, EXTEND-vs-CREATE threshold, ambiguous-match and closed-item handling). **This skill's parent scope**: the selected epic. First, check each candidate's idempotency key against the registry: an exact match to an existing **open** story is `ALREADY EXISTS #ID` (skip) — per to-issues-triage.md's Skip step, not a triage decision. For every remaining candidate, classify `EXTEND #ID` or `CREATE` — or, if ambiguous (per to-issues-triage.md), present it as a question with a recommendation instead of silently picking one side. Present the triage proposal to developer: +2. **Act**: Apply vertical slicing — every story must deliver end-to-end user value with visible UI manifestation. This rule governs CREATE candidates only — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)'s per-skill-delta note. +3. **Act**: Triage each candidate story against the Step 2 registry — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md) for the matching shape (idempotency key, EXTEND-vs-CREATE threshold, ambiguous-match and closed-item handling). **This skill's parent scope**: the selected epic. First, check each candidate's idempotency key against the registry: an exact match to an existing **open** story is `ALREADY EXISTS #ID` (skip) — per to-issues-triage.md's Skip step, not a triage decision. For every remaining candidate, classify `EXTEND #ID` or `CREATE` — or, if ambiguous (per to-issues-triage.md), present it as a question with a recommendation instead of silently picking one side. Present the triage proposal to developer: > Story candidates for Epic `#[ID]: [Title]`: > @@ -94,7 +94,7 @@ For each approved story, per its Step 3 proposal: > Story `[Title]` already exists (#ID). Skipping. -3. **Act**: Define story scope using the Initial Breakdown section of [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: Define story scope using the Initial Breakdown section of [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Story statement (As a / I want / So that). - Rough scope boundaries with expected uncertainty. - Initial sizing: XS(1), S(2), M(3), L(5), XL(8). @@ -148,13 +148,13 @@ STORIES COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 and extends story issues linked to epics. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md) and [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md). This skill's check: exact idempotency-key match is proposed `ALREADY EXISTS #ID` (skip) at triage time, before any write (Step 3) — Step 4 only executes the confirmed proposal; substantial-overlap match proposes EXTEND instead of a duplicate CREATE (Step 3) — re-running the same candidate tree never duplicates. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) and [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md). This skill's check: exact idempotency-key match is proposed `ALREADY EXISTS #ID` (skip) at triage time, before any write (Step 3) — Step 4 only executes the confirmed proposal; substantial-overlap match proposes EXTEND instead of a duplicate CREATE (Step 3) — re-running the same candidate tree never duplicates. - Stories at breakdown stage are rough planning units — detailed requirements are added during `/pair-process-refine-story`. - INVEST validation is mandatory for CREATE candidates — stories failing INVEST must be reworked before creation. EXTEND candidates re-validate INVEST for the merged scope (Step 4). diff --git a/.claude/skills/pair-process-plan-tasks/SKILL.md b/.claude/skills/pair-process-plan-tasks/SKILL.md index 2d7f78b6..af931f27 100644 --- a/.claude/skills/pair-process-plan-tasks/SKILL.md +++ b/.claude/skills/pair-process-plan-tasks/SKILL.md @@ -90,7 +90,7 @@ Transform a refined user story into specific, actionable implementation tasks. T For each task (skipping tasks that already exist in the story body): -1. **Act**: Define the task following the [task-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/task-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +1. **Act**: Define the task following the [task-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/task-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Task Information (ID, priority, hours, bounded context) - Summary and type - Description with implementation context @@ -157,13 +157,13 @@ TASK BREAKDOWN COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. -- **Idempotent (task-level)** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-invoking on a story with partial tasks adds only the missing ones (the caller composes the full updated body; write-issue overwrites it). +- **Idempotent (task-level)** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). This skill's check: re-invoking on a story with partial tasks adds only the missing ones (the caller composes the full updated body; write-issue overwrites it). - 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 975c6828..ec38deef 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 (single Draft→Ready) -Transform a user story from rough breakdown (Draft) into a development-ready specification (Ready). This is **THE single Draft→Ready path** — no separate "make-ready" skill exists and none is ever born (R3.12, D24); refinement IS the transition (canonical-states.md). **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, an already-Ready story is confirmed and exits. +Transform a user story from rough breakdown (Draft) into a development-ready specification (Ready). This is **THE single Draft→Ready path** — no separate "make-ready" skill exists and none is ever born (R3.12, D24); refinement IS the transition (canonical-states.md). **Section-level idempotency** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md): each refinement section is checked before acting; partial refinements resume from the first missing section, an already-Ready story is confirmed and exits. ## Composed Skills @@ -138,7 +138,7 @@ Transform a user story from rough breakdown (Draft) into a development-ready spe ### Step 5: Documentation and PM Tool Update -1. **Act**: Assemble the complete refined story body using the [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)) Refined template: +1. **Act**: Assemble the complete refined story body using the [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)) Refined template: - **Functional sections first**: Story Statement → Epic Context → Classification (the Step 3b matrix) → Acceptance Criteria → Definition of Done → Story Sizing → Dependencies → Validation → Notes. - **Technical sections last**: Technical Analysis → (Task Breakdown added later by `/pair-process-plan-tasks`). 2. **Act**: Compose `/pair-capability-write-issue` with: @@ -189,7 +189,7 @@ STORY REFINEMENT COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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: - **`/pair-capability-grill` not installed** (Phase 0): warn and skip the sync; the per-step human-judgment approval gates in Steps 2–4 remain the alignment mechanism — refinement still completes. - **`/pair-capability-map-subdomains` / `/pair-capability-map-contexts` not installed, or no domain artifacts** (Steps 2–3): the functional and technical analysis sections are still produced; domain placement and touched-context mapping are skipped with a note, and the coupling dimension is "not assessed" (never a HALT). diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 9f24edc3..dfd413d7 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -53,7 +53,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 — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md): +3. **Act**: Read PR from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md): - PR metadata (author, branch, target, status) - Changed files and diff - PR description and linked story @@ -191,7 +191,7 @@ Run the procedure for the level determined in Step 3.1 — see [degradation-leve ### Step 5.1: Compile Review Report -1. **Act**: Compile all findings into a review report following the [code-review-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/code-review-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +1. **Act**: Compile all findings into a review report following the [code-review-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/code-review-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - **Review Information**: PR number, author, reviewer, date, story, review type - **Review Summary**: overall assessment, key changes, business value - **Code Review Checklist**: functionality, code quality, technical standards (from Phase 2) @@ -271,7 +271,7 @@ On HALT: report the blocker, compose the resolution skill if available, wait for ## Idempotent Re-invocation -See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/pair-process-review` on a partially reviewed PR is safe — per-phase: +See [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -282,7 +282,7 @@ See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempote ## 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -299,7 +299,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - 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 (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). +- The reviewer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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-review/merge-and-cascade.md b/.claude/skills/pair-process-review/merge-and-cascade.md index dbeedc09..124c937e 100644 --- a/.claude/skills/pair-process-review/merge-and-cascade.md +++ b/.claude/skills/pair-process-review/merge-and-cascade.md @@ -11,7 +11,7 @@ Disclosed from [SKILL.md](./SKILL.md) Phase 6 — only reached when the reviewer ### Step 6.2: Prepare Merge Commit -1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): ```text [#] feat: diff --git a/.claude/skills/pair-process-specify-prd/SKILL.md b/.claude/skills/pair-process-specify-prd/SKILL.md index 02600848..ae421e8d 100644 --- a/.claude/skills/pair-process-specify-prd/SKILL.md +++ b/.claude/skills/pair-process-specify-prd/SKILL.md @@ -180,7 +180,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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." diff --git a/.pair/knowledge/guidelines/README.md b/.pair/knowledge/guidelines/README.md index 9e9bf5ec..c159ccb5 100644 --- a/.pair/knowledge/guidelines/README.md +++ b/.pair/knowledge/guidelines/README.md @@ -56,6 +56,7 @@ Development guidelines are organized into three specialized practice areas: - **[Coding Standards](technical-standards/coding-standards/README.md)** - Coding conventions and standards - **[Git Workflow](technical-standards/git-workflow/README.md)** - Version control and development process - **[AI Development](technical-standards/ai-development/README.md)** - AI/ML development standards and practices + - **[Skill Conventions](technical-standards/ai-development/skill-conventions/README.md)** - Single-source shared conventions for the `SKILL.md` corpus - **[Testing](testing/README.md)** - How to verify that software works correctly - **[Test Strategy](testing/test-strategy/README.md)** - Testing philosophy, pyramid strategy, and comprehensive approaches diff --git a/.pair/knowledge/guidelines/architecture/design-patterns/context-map-maintenance.md b/.pair/knowledge/guidelines/architecture/design-patterns/context-map-maintenance.md index ac62290d..064637de 100644 --- a/.pair/knowledge/guidelines/architecture/design-patterns/context-map-maintenance.md +++ b/.pair/knowledge/guidelines/architecture/design-patterns/context-map-maintenance.md @@ -20,7 +20,7 @@ Apply these four checks whenever the session's domain step is reached. They are ### 1. Challenge the Glossary -Before adding a term, check whether `context-map.md` (or the relevant `subdomain/.context.md`) already has it, or something close enough to conflict. Read the [Subdomain Index](../../collaboration/templates/context-map-template.md) (resolve override-first — [template resolution](../../../skill-conventions/template-resolution.md)) first to know which subdomains keep their context inline versus split out. +Before adding a term, check whether `context-map.md` (or the relevant `subdomain/.context.md`) already has it, or something close enough to conflict. Read the [Subdomain Index](../../collaboration/templates/context-map-template.md) (resolve override-first — [template resolution](../../technical-standards/ai-development/skill-conventions/template-resolution.md)) first to know which subdomains keep their context inline versus split out. ### 2. Sharpen Vague Terms @@ -44,7 +44,7 @@ The map starts as a single file. Splitting is **lazy and human-approved — neve - **Signal to propose a split**: a subdomain's inline Glossary/Entities rows in `context-map.md` have grown large enough that scanning the shared file for unrelated subdomains becomes noisy, or the subdomain's context changes far more often than the rest of the map. - **Propose, don't act**: the maintaining session states the reason and asks for approval — e.g. "`billing`'s glossary is now 12 terms; move it to its own context file?" Proceed only once the human agrees. -- **What moves**: every Glossary and Entities row scoped to that subdomain moves to the co-located sibling `subdomain/.context.md` (see [subdomain-context-template.md](../../collaboration/templates/subdomain-context-template.md) — resolve override-first per [template resolution](../../../skill-conventions/template-resolution.md)), sitting next to the strategic `subdomain/.md` catalog file. +- **What moves**: every Glossary and Entities row scoped to that subdomain moves to the co-located sibling `subdomain/.context.md` (see [subdomain-context-template.md](../../collaboration/templates/subdomain-context-template.md) — resolve override-first per [template resolution](../../technical-standards/ai-development/skill-conventions/template-resolution.md)), sitting next to the strategic `subdomain/.md` catalog file. - **What stays**: the Subdomain Index row (flipped to "Yes" under Own Context) and the entire Common Rules and Invariants section — domain-wide rules are never split, since they aren't owned by one subdomain. - **Never re-map automatically**: a later session may propose merging a context file back inline if it shrinks, but this again requires human approval — the guideline never rewrites the split on its own. @@ -66,8 +66,8 @@ Any skill that touches domain scope (brainstorm's domain step, refine-story's re ## Related Documents -- **[Context Map Template](../../collaboration/templates/context-map-template.md)** — the dispatcher + index + core artifact this guideline maintains (resolve override-first per [template resolution](../../../skill-conventions/template-resolution.md)) -- **[Subdomain Context Template](../../collaboration/templates/subdomain-context-template.md)** — the lazy-split sibling file (resolve override-first per [template resolution](../../../skill-conventions/template-resolution.md)) +- **[Context Map Template](../../collaboration/templates/context-map-template.md)** — the dispatcher + index + core artifact this guideline maintains (resolve override-first per [template resolution](../../technical-standards/ai-development/skill-conventions/template-resolution.md)) +- **[Subdomain Context Template](../../collaboration/templates/subdomain-context-template.md)** — the lazy-split sibling file (resolve override-first per [template resolution](../../technical-standards/ai-development/skill-conventions/template-resolution.md)) - **[Strategic Subdomain Definition](strategic-subdomain-definition.md)** — subdomain catalog and classification, source of the mirrored Volatility column - **[Domain-Driven Design](domain-driven-design.md)** — overall DDD principles this guideline operationalizes as a maintenance process - **[Decision Records](../decision-frameworks/README.md)** — ADR/DDR process for domain decisions cited during conflict-flagging diff --git a/.pair/knowledge/guidelines/technical-standards/ai-development/README.md b/.pair/knowledge/guidelines/technical-standards/ai-development/README.md index 1d659aaf..c27f7d4a 100644 --- a/.pair/knowledge/guidelines/technical-standards/ai-development/README.md +++ b/.pair/knowledge/guidelines/technical-standards/ai-development/README.md @@ -13,6 +13,7 @@ Establish enterprise-grade standards for AI development that maximize developmen - **[AI Tools](ai-tools.md)** - AI development tool selection, configuration, and best practices - **[Documentation Standards](documentation-standards.md)** - AI-specific documentation requirements and patterns - **[MCP Integration](mcp-integration.md)** - Model Context Protocol implementation and integration standards +- **[Skill Conventions](skill-conventions/README.md)** - Single-source shared conventions for the `SKILL.md` corpus (resolution cascade, idempotency, graceful degradation, template resolution, PM-tool resolution, and more) ### Key Focus Areas diff --git a/.pair/knowledge/skill-conventions/README.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/README.md similarity index 100% rename from .pair/knowledge/skill-conventions/README.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/README.md diff --git a/.pair/knowledge/skill-conventions/graceful-degradation.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md similarity index 100% rename from .pair/knowledge/skill-conventions/graceful-degradation.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md diff --git a/.pair/knowledge/skill-conventions/guided-quick-setup.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/guided-quick-setup.md similarity index 100% rename from .pair/knowledge/skill-conventions/guided-quick-setup.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/guided-quick-setup.md diff --git a/.pair/knowledge/skill-conventions/idempotency.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md similarity index 100% rename from .pair/knowledge/skill-conventions/idempotency.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md diff --git a/.pair/knowledge/skill-conventions/output-shapes.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md similarity index 100% rename from .pair/knowledge/skill-conventions/output-shapes.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md diff --git a/.pair/knowledge/skill-conventions/record-decision-contract.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md similarity index 100% rename from .pair/knowledge/skill-conventions/record-decision-contract.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md diff --git a/.pair/knowledge/skill-conventions/resolution-cascade.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md similarity index 100% rename from .pair/knowledge/skill-conventions/resolution-cascade.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md diff --git a/.pair/knowledge/skill-conventions/template-resolution.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md similarity index 100% rename from .pair/knowledge/skill-conventions/template-resolution.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md diff --git a/.pair/knowledge/skill-conventions/to-issues-triage.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md similarity index 100% rename from .pair/knowledge/skill-conventions/to-issues-triage.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md diff --git a/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md similarity index 75% rename from .pair/knowledge/skill-conventions/way-of-working-pm-resolution.md rename to .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md index 6b3c8ef7..259a6f32 100644 --- a/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md +++ b/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md @@ -4,7 +4,7 @@ How any skill that needs the project's PM tool (to read or write a story/PR/epic ## 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. +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**: @@ -14,7 +14,7 @@ How any skill that needs the project's PM tool (to read or write a story/PR/epic ## 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. +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) diff --git a/.pair/llms.txt b/.pair/llms.txt index 57d612e5..f31f70c8 100644 --- a/.pair/llms.txt +++ b/.pair/llms.txt @@ -329,6 +329,16 @@ - [AI Development Documentation Standards](.pair/knowledge/guidelines/technical-standards/ai-development/documentation-standards.md) - [Model Context Protocol (MCP) Integration](.pair/knowledge/guidelines/technical-standards/ai-development/mcp-integration.md) - [AI Development Standards](.pair/knowledge/guidelines/technical-standards/ai-development/README.md) +- [Graceful Degradation — Standard Bullets](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) +- [Guided / Quick Setup Convention](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/guided-quick-setup.md) +- [Idempotency Convention](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) +- [Output Format Shapes](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md) +- [Skill Conventions — Shared KB References](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/README.md) +- [`/pair-capability-record-decision` Invocation Contract](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) +- [Resolution Cascade](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) +- [Template Resolution](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md) +- [To-Issues Triage (Extend vs Create)](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md) +- [Way-of-Working / PM-Tool Resolution](.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md) - [Error Handling Standards](.pair/knowledge/guidelines/technical-standards/coding-standards/error-handling.md) - [Internationalization and Localization (i18n/l10n)](.pair/knowledge/guidelines/technical-standards/coding-standards/i18n-localization.md) - [Coding Standards](.pair/knowledge/guidelines/technical-standards/coding-standards/README.md) diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 4f79611c..485fbfbc 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -138,7 +138,7 @@ A skill or CLI command that collects inputs to produce or configure something (p Both modes read the **same resolved defaults** through one precedence cascade — `explicit argument/flag > project state > saved/inferred preferences > hardcoded` — the mode only decides whether each value is confirmed or taken as-is. This is the `pair package` command's `--interactive` flag + `resolveDefaults()` cascade (both the quick and guided paths resolve it), and the `assess-*` family's resolution cascade (Path A override = quick, Path C = guided). -Adopt the convention directly rather than re-designing the duality — the full mechanics, precedents, and edge cases live in the KB reference `.pair/knowledge/skill-conventions/guided-quick-setup.md`. +Adopt the convention directly rather than re-designing the duality — the full mechanics, precedents, and edge cases live in the KB reference `.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/guided-quick-setup.md`. ## The effectiveness standard diff --git a/apps/website/content/docs/customization/templates.mdx b/apps/website/content/docs/customization/templates.mdx index bba2e741..f0f049b5 100644 --- a/apps/website/content/docs/customization/templates.mdx +++ b/apps/website/content/docs/customization/templates.mdx @@ -84,7 +84,7 @@ The AI reads these templates when creating the corresponding artifacts — but i Templates live in `.pair/knowledge/` — the upstream layer that gets overwritten on `pair-cli update`. To customize safely, create an override in the adoption layer. -**How resolution works:** every skill that uses a template resolves it **override-first** by a plain file-existence check — if `.pair/adoption/tech/templates/-template.md` exists (where `-template.md` matches a shipped KB filename above), the skill uses your copy whole; otherwise it uses the KB default. There is no partial merge and no prose to keep in sync — dropping the file in place is the entire mechanism. (Skill-side contract: `.pair/knowledge/skill-conventions/template-resolution.md`.) +**How resolution works:** every skill that uses a template resolves it **override-first** by a plain file-existence check — if `.pair/adoption/tech/templates/-template.md` exists (where `-template.md` matches a shipped KB filename above), the skill uses your copy whole; otherwise it uses the KB default. There is no partial merge and no prose to keep in sync — dropping the file in place is the entire mechanism. (Skill-side contract: `.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md`.) ### Step 1: Copy the Template diff --git a/apps/website/content/docs/reference/guidelines-catalog.mdx b/apps/website/content/docs/reference/guidelines-catalog.mdx index 9e0521cf..6299780b 100644 --- a/apps/website/content/docs/reference/guidelines-catalog.mdx +++ b/apps/website/content/docs/reference/guidelines-catalog.mdx @@ -120,6 +120,7 @@ Coding standards, git workflow, and tooling. | Topic | What it covers | | --- | --- | | **AI Development** | AI tool configuration, prompt patterns, agent integration | +| **AI Development → Skill Conventions** | Single-source shared conventions for the `SKILL.md` corpus (resolution cascade, idempotency, graceful degradation, template resolution) | | **Coding Standards** | Language-specific conventions, linting rules | | **Deployment Workflow** | Release process, versioning, changelog | | **Development Tools** | IDE setup, debugging, profiling | diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/README.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/README.md index 9e9bf5ec..c159ccb5 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/README.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/README.md @@ -56,6 +56,7 @@ Development guidelines are organized into three specialized practice areas: - **[Coding Standards](technical-standards/coding-standards/README.md)** - Coding conventions and standards - **[Git Workflow](technical-standards/git-workflow/README.md)** - Version control and development process - **[AI Development](technical-standards/ai-development/README.md)** - AI/ML development standards and practices + - **[Skill Conventions](technical-standards/ai-development/skill-conventions/README.md)** - Single-source shared conventions for the `SKILL.md` corpus - **[Testing](testing/README.md)** - How to verify that software works correctly - **[Test Strategy](testing/test-strategy/README.md)** - Testing philosophy, pyramid strategy, and comprehensive approaches diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/architecture/design-patterns/context-map-maintenance.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/architecture/design-patterns/context-map-maintenance.md index ac62290d..064637de 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/architecture/design-patterns/context-map-maintenance.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/architecture/design-patterns/context-map-maintenance.md @@ -20,7 +20,7 @@ Apply these four checks whenever the session's domain step is reached. They are ### 1. Challenge the Glossary -Before adding a term, check whether `context-map.md` (or the relevant `subdomain/.context.md`) already has it, or something close enough to conflict. Read the [Subdomain Index](../../collaboration/templates/context-map-template.md) (resolve override-first — [template resolution](../../../skill-conventions/template-resolution.md)) first to know which subdomains keep their context inline versus split out. +Before adding a term, check whether `context-map.md` (or the relevant `subdomain/.context.md`) already has it, or something close enough to conflict. Read the [Subdomain Index](../../collaboration/templates/context-map-template.md) (resolve override-first — [template resolution](../../technical-standards/ai-development/skill-conventions/template-resolution.md)) first to know which subdomains keep their context inline versus split out. ### 2. Sharpen Vague Terms @@ -44,7 +44,7 @@ The map starts as a single file. Splitting is **lazy and human-approved — neve - **Signal to propose a split**: a subdomain's inline Glossary/Entities rows in `context-map.md` have grown large enough that scanning the shared file for unrelated subdomains becomes noisy, or the subdomain's context changes far more often than the rest of the map. - **Propose, don't act**: the maintaining session states the reason and asks for approval — e.g. "`billing`'s glossary is now 12 terms; move it to its own context file?" Proceed only once the human agrees. -- **What moves**: every Glossary and Entities row scoped to that subdomain moves to the co-located sibling `subdomain/.context.md` (see [subdomain-context-template.md](../../collaboration/templates/subdomain-context-template.md) — resolve override-first per [template resolution](../../../skill-conventions/template-resolution.md)), sitting next to the strategic `subdomain/.md` catalog file. +- **What moves**: every Glossary and Entities row scoped to that subdomain moves to the co-located sibling `subdomain/.context.md` (see [subdomain-context-template.md](../../collaboration/templates/subdomain-context-template.md) — resolve override-first per [template resolution](../../technical-standards/ai-development/skill-conventions/template-resolution.md)), sitting next to the strategic `subdomain/.md` catalog file. - **What stays**: the Subdomain Index row (flipped to "Yes" under Own Context) and the entire Common Rules and Invariants section — domain-wide rules are never split, since they aren't owned by one subdomain. - **Never re-map automatically**: a later session may propose merging a context file back inline if it shrinks, but this again requires human approval — the guideline never rewrites the split on its own. @@ -66,8 +66,8 @@ Any skill that touches domain scope (brainstorm's domain step, refine-story's re ## Related Documents -- **[Context Map Template](../../collaboration/templates/context-map-template.md)** — the dispatcher + index + core artifact this guideline maintains (resolve override-first per [template resolution](../../../skill-conventions/template-resolution.md)) -- **[Subdomain Context Template](../../collaboration/templates/subdomain-context-template.md)** — the lazy-split sibling file (resolve override-first per [template resolution](../../../skill-conventions/template-resolution.md)) +- **[Context Map Template](../../collaboration/templates/context-map-template.md)** — the dispatcher + index + core artifact this guideline maintains (resolve override-first per [template resolution](../../technical-standards/ai-development/skill-conventions/template-resolution.md)) +- **[Subdomain Context Template](../../collaboration/templates/subdomain-context-template.md)** — the lazy-split sibling file (resolve override-first per [template resolution](../../technical-standards/ai-development/skill-conventions/template-resolution.md)) - **[Strategic Subdomain Definition](strategic-subdomain-definition.md)** — subdomain catalog and classification, source of the mirrored Volatility column - **[Domain-Driven Design](domain-driven-design.md)** — overall DDD principles this guideline operationalizes as a maintenance process - **[Decision Records](../decision-frameworks/README.md)** — ADR/DDR process for domain decisions cited during conflict-flagging diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/README.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/README.md index 514ab02e..bc83716e 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/README.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/README.md @@ -13,6 +13,7 @@ Establish enterprise-grade standards for AI development that maximize developmen - **[AI Tools](ai-tools.md)** - AI development tool selection, configuration, and best practices - **[Documentation Standards](documentation-standards.md)** - AI-specific documentation requirements and patterns - **[MCP Integration](mcp-integration.md)** - Model Context Protocol implementation and integration standards +- **[Skill Conventions](skill-conventions/README.md)** - Single-source shared conventions for the `SKILL.md` corpus (resolution cascade, idempotency, graceful degradation, template resolution, PM-tool resolution, and more) ### Key Focus Areas diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/README.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/README.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/README.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/README.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/graceful-degradation.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/graceful-degradation.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/guided-quick-setup.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/guided-quick-setup.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/guided-quick-setup.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/guided-quick-setup.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/idempotency.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/idempotency.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/output-shapes.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/output-shapes.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/record-decision-contract.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/record-decision-contract.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/resolution-cascade.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/resolution-cascade.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/template-resolution.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/template-resolution.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/to-issues-triage.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md similarity index 100% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/to-issues-triage.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md similarity index 75% rename from packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md rename to packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md index 0d00105e..af235688 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md @@ -4,7 +4,7 @@ How any skill that needs the project's PM tool (to read or write a story/PR/epic ## 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. +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**: @@ -14,7 +14,7 @@ How any skill that needs the project's PM tool (to read or write a story/PR/epic ## 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. +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) 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 b90a84de..dfcce3aa 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,7 +20,7 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p ### Step 1: Resolution Cascade -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). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) check (no Path A/Argument-Override). - **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. @@ -103,7 +103,7 @@ 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). +Follows the [Report Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#report-shape). ```text CODE QUALITY REPORT: @@ -141,7 +141,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -150,7 +150,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill is **read-only / output-only** — it only inspects code and runs coverage (via existing test commands); files, adoption, and the PM tool stay untouched. A finding worth tracking is promoted deliberately to the backlog via `/write-issue` — always a manual, selective act. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 06776a24..090506d0 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md @@ -24,7 +24,7 @@ This skill is **output-only** — it composes no skill and writes no files. No a ### Step 1: Resolution Cascade -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. +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) check against a recent output rather than an adoption file. - **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. @@ -133,7 +133,7 @@ For each detected item, apply the prioritization formula: ## Output Format -Follows the [Report Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#report-shape). +Follows the [Report Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#report-shape). ```text TECH DEBT ANALYSIS (output-only — no files or issues created): @@ -171,13 +171,13 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. ## Notes -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: existing analysis for the codebase/PR (Step 1, Path B). +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 d9426a70..0b6e2f48 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this section — the caller writes ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -92,11 +92,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -111,7 +111,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/bootstrap`: @@ -129,7 +129,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for AI tool preferences directly) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 5b139a55..57f121d2 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this file — the caller writes it ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -82,11 +82,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -101,7 +101,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/bootstrap`: @@ -119,7 +119,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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-cost/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-cost/SKILL.md index 9048235f..70e126bc 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-cost/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-cost/SKILL.md @@ -118,7 +118,7 @@ When invoked **independently** (`/assess-cost` on a branch or story): full one-s ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment against §3.3 alone, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → n/a in `$diff` mode) for the standard scenarios. Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment against §3.3 alone, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → n/a in `$diff` mode) for the standard scenarios. Additional cases: - **cost-assessment guideline absent** (KB partially installed): assess against quality-model §3.3's inline signal list only, and note the reduced catalog in the output rather than HALTing. - **`/classify` not available** (independent invocation): the class is still emitted; it simply isn't folded into a compiled matrix by a caller — the developer reads the verdict directly. @@ -127,6 +127,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - **Writes nothing** — the strict output-only convention of the assess-* family (unlike `assess-security`, this skill has no report/audit mode: report/monitoring is deliberately split to a separate slice). The class is data for `/classify`/`/review`, never an action this skill takes. - **Never blocks** — no merge authority; a `red` class is a signal for the caller, not a gate this skill enforces. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): a fresh class is computed every run against the current diff/story by design (signals change commit to commit); no cached verdict. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md): a fresh class is computed every run against the current diff/story by design (signals change commit to commit); no cached verdict. - **Provider-agnostic** — adding a provider is an adoption/KB change (a per-provider section in the guideline, or an adoption link), never a change to this skill (R2.13). - **D22** (1-line verdict + collapsed details): a project-level rendering decision the caller honors; this skill emits in that shape. 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 4be468ed..e9a8eddd 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this file — the caller writes it ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -82,11 +82,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -101,7 +101,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/bootstrap`: @@ -118,7 +118,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for CI/CD and deployment preferences directly) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 5df74466..edd4210e 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this section — the caller writes ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -87,11 +87,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -106,7 +106,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/bootstrap`: @@ -123,7 +123,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for methodology preference based on team size/requirements stability) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 56e7f0ec..3523bc3e 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this section — the caller writes ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -85,11 +85,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -104,7 +104,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/bootstrap`: @@ -121,7 +121,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for platform preference directly) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 82dbc36c..24c54c24 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md @@ -34,7 +34,7 @@ The rendered adoption content is destined for this section — the caller (or `/ ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -91,11 +91,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). +3. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). ## 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). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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): @@ -110,7 +110,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/bootstrap`: @@ -127,7 +127,7 @@ When invoked **independently**: if `/setup-pm` is present it persists; otherwise ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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-security/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-security/SKILL.md index d569df8e..2cf55825 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-security/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-security/SKILL.md @@ -65,7 +65,7 @@ Every rule the skill applies is resolved through the same layered set, most-spec ### Step 5: Resolution Cascade -See [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics. +See [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics. - **Path A** ($choice provided): adopt the named control set (e.g. `owasp-top10`) directly — render the `tech/security.md` proposal referencing it, skip full evaluation, confirm with the developer. Proceed to Step 8. - **Path B** (adoption check): `adoption/tech/security.md` exists with a populated project-rules section. Confirm it's still current with the developer; if its backing decision record is missing, report the gap (this skill still writes nothing to adoption — the caller backfills via `/record-decision`). No audit report is generated for an unchanged, confirmed ruleset ("no re-assessment", per the resolution cascade addendum). Exit. @@ -86,7 +86,7 @@ See [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-c ### Step 8: Render Project-Rules Proposal 1. **Act**: Render the `tech/security.md` content: global project security principles distilled from the audit findings (never duplicating KB or per-service/per-web-app guideline content — only the project-specific delta). -2. **Act**: Assemble the persistence tuple per [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md): +2. **Act**: Assemble the persistence tuple per [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md): - `content`: the rendered `tech/security.md` body. - `target`: `adoption/tech/security.md`. - `decision-metadata`: `$type: non-architectural`, `$topic: security-strategy-initial` (first audit) or `security-strategy-update` (subsequent), `$summary: "Project security rules adopted from audit: [key rules]"`. @@ -148,7 +148,7 @@ When invoked **independently** in audit mode: ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment, ask directly; adoption file missing → skill still runs against KB defaults; PM tool unreachable → n/a, this skill doesn't read the PM tool) for the standard scenarios. Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → minimal assessment, ask directly; adoption file missing → skill still runs against KB defaults; PM tool unreachable → n/a, this skill doesn't read the PM tool) for the standard scenarios. Additional cases: - **Package-scoped override (#237) not active**: load only the root `adoption/tech/security.md` (layer 4) — the package-scoped layer 5 is skipped entirely, not an error. - **`/map-contexts` not available** (for per-service/per-web-app boundary detection in review mode): fall back to inferring service/web-app boundaries from package structure (framework markers, `package.json` fields) rather than HALTing. @@ -157,6 +157,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - **Writes exactly one kind of file itself**: the audit report under `.pair/working/reports/security/` (Step 7) — the one exception to the `assess-*` family's usual output-only convention, justified the same way `/design-manual-tests` writes its own suite files: reports are operational artifacts (D14), not adoption content. Adoption content (`tech/security.md`) is never self-written — that always goes through the caller's `/record-decision` composition (Step 8). -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Audit mode's check: Path B (populated `tech/security.md` + backing decision record) confirms rather than re-running the full OWASP assessment. Review mode is not idempotent in that sense — a fresh verdict is computed every review, against the current diff, by design (findings can change commit to commit). +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). Audit mode's check: Path B (populated `tech/security.md` + backing decision record) confirms rather than re-running the full OWASP assessment. Review mode is not idempotent in that sense — a fresh verdict is computed every review, against the current diff, by design (findings can change commit to commit). - **Never scans for secrets**: committed-secret detection is a deterministic, LLM-free CI layer (R6.5) provisioned by `/setup-gates`, not an assessment this skill performs — keeping the "no LLM involved" guarantee real (D24). - **D22** (1-line verdict + collapsed findings, never a table inline): a project-level decision record, not part of this portable dataset. 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 141dbb36..4d78fbfd 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md @@ -58,7 +58,7 @@ Detect and evaluate unlisted dependencies. Used when `/review` finds a dependenc ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -152,7 +152,7 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - **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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). ## Version Tracking Policy @@ -174,7 +174,7 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- ## 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). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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): @@ -190,7 +190,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/bootstrap`: @@ -222,7 +222,7 @@ When invoked **independently**: mode auto-detected. The skill returns the propos ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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 in implementation/review mode (as opposed to bootstrap, covered above), HALT: "No tech stack defined — run /assess-stack in bootstrap mode first." 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 59a03c93..7d192819 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md @@ -30,7 +30,7 @@ The rendered adoption content is destined for this section — the caller writes ### Step 1: Resolution Cascade -Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). +Read [resolution cascade](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/resolution-cascade.md) for the generic Path A/B/C mechanics (check → skip → act → verify). - **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`). @@ -88,11 +88,11 @@ Read [resolution cascade](../../../.pair/knowledge/skill-conventions/resolution- - `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 — see [record-decision invocation contract](../../../.pair/knowledge/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). +2. **Verify**: Proposal emitted — see [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the persistence contract (persistence is always the caller's responsibility, delegated to `/record-decision`). ## Output Format -Follows the [Decision Shape](../../../.pair/knowledge/skill-conventions/output-shapes.md#decision-shape). +Follows the [Decision Shape](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/output-shapes.md#decision-shape). ```text ASSESSMENT COMPLETE (output-only — no files written): @@ -107,7 +107,7 @@ 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. +See [record-decision invocation contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/record-decision-contract.md) for the generic tuple + Input/Output/Persistence shape. When composed by `/bootstrap`: @@ -126,7 +126,7 @@ When invoked **independently**: the human (or agent) persists the proposal by co ## Graceful Degradation -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. +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → ask developer for framework preference based on language) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 4decd2d1..7234c341 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md @@ -7,7 +7,7 @@ author: Foomakers # /checkpoint — Resumable Progress State -Write and resume a self-contained progress checkpoint so a fresh session (or a subagent) can continue a story exactly where the previous one stopped. Follows the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)) — five sections: story, branch, tasks done, key decisions, remaining todos. +Write and resume a self-contained progress checkpoint so a fresh session (or a subagent) can continue a story exactly where the previous one stopped. Follows the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)) — five sections: story, branch, tasks done, key decisions, remaining todos. ## Arguments @@ -179,7 +179,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -188,7 +188,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **writes at most one file** — `.pair/working/checkpoints/.md` — and only in write mode with `$persist=true` (default). -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/classify/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/classify/SKILL.md index 9aa3c19b..5c1b9c7c 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/classify/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/classify/SKILL.md @@ -170,7 +170,7 @@ Review raw max = red (Change/diff risk, Security relevance), so `max(red, yellow ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline missing → minimal run, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → matrix returned to caller, tagging deferred). Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline missing → minimal run, ask directly; adoption file missing → run against KB defaults; PM tool unreachable → matrix returned to caller, tagging deferred). Additional cases: - **`/assess-security` not available** (review): fall back to the path-heuristic security relevance (quality-model §3.1) instead of the verdict; note the fallback. - **`/assess-coupling` not installed / no DDD artifacts**: coupling dimension "not assessed" (never a HALT). @@ -184,4 +184,4 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - **Reading budget** (D22): the body/report output is 1 line + `
`, never an inline table. - **Writes two kinds of thing itself**: the matrix into the card/PR body (Step 4) and — only on a confirmed first-run proposal — the `## Tag Projection` registry section in `tech/risk-matrix.md` (Step 5, the quality-model §5 self-write precedent, mirroring `/verify-quality`'s Custom Gate Registry). Adoption **decision** content is never self-written — that routes through `/record-decision`; the Tag Projection section is config-registry state, not a decision record. - **No eligibility tag**: automation eligibility is an adoption-declared filter over classification tags (`risk:green`, …), not a special tag — `/next` consumes it generically (quality-model §5, D18). -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md): re-running on an already-classified card recomputes the same matrix; a declared or opted-out Tag Projection is never re-proposed. Review re-runs recompute against the current diff (a raise can happen commit-to-commit; a lower never can). +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md): re-running on an already-classified card recomputes the same matrix; a declared or opted-out Tag Projection is never re-proposed. Review re-runs recompute against the current diff (a raise can happen commit-to-commit; a lower never can). 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 561e885e..0a4893ee 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 @@ -9,7 +9,7 @@ author: Foomakers Analyze a project's released artifacts, deployment targets, and user-facing surfaces to generate a complete manual test suite. Produces critical path files (`CP*.md`) and a suite `README.md` in the test suite directory. -Each test case follows the [manual-test-case-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-case-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)). Design principles: [manual-testing.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-testing.md); organizational context: [manual-verification.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-verification.md). +Each test case follows the [manual-test-case-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-case-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)). Design principles: [manual-testing.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-testing.md); organizational context: [manual-verification.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-verification.md). ## Arguments @@ -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. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-running on an existing suite offers regenerate/extend/abort. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 94f277a5..b7f51229 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 — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md). +1. **Check**: Read the story from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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,7 +108,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 the story has no acceptance criteria, warn: "Story lacks AC — estimation may be inaccurate. Consider refining first." @@ -116,6 +116,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **modifies the PM tool** — it writes the estimate to the story issue. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 29951d1b..d8dd4ae1 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 @@ -7,7 +7,7 @@ author: Foomakers # /execute-manual-tests — Manual Test Suite Executor -Execute a manual test suite against released or deployed artifacts (website, CLI packages, registries). Produces a structured report following the [manual-test-report-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-report-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)). +Execute a manual test suite against released or deployed artifacts (website, CLI packages, registries). Produces a structured report following the [manual-test-report-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-report-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)). Reads test case files from the project's manual test suite directory; each follows the [manual-test-case-template](../../../.pair/knowledge/guidelines/collaboration/templates/manual-test-case-template.md). Organizational context (who, when, which areas): [manual-verification.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-verification.md); test case design principles: [manual-testing.md](../../../.pair/knowledge/guidelines/quality-assurance/manual-testing.md). @@ -162,11 +162,11 @@ 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** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-executing produces the same result without manual cleanup. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). This skill's check: re-executing produces the same result without manual cleanup. ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → use a minimal structure directly) for the standard scenarios. Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. diff --git a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md index 633094e3..22fbe9ac 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md @@ -92,7 +92,7 @@ Systematic AI↔human alignment on a specific story, covering all six aspects of 1. **Act**: Compile recorded answers, explored facts (with source), and flagged assumptions: - `interview` → raw requirements blob (topic, findings per sub-question, open items, assumptions). - - `sync` → alignment synthesis mapped to the six [Sync Coverage Checklist](#sync-coverage-checklist) aspects, ready to drop into the matching [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)) sections. + - `sync` → alignment synthesis mapped to the six [Sync Coverage Checklist](#sync-coverage-checklist) aspects, ready to drop into the matching [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)) sections. 2. **Verify**: Synthesis accounts for every answered/explored/assumed item — nothing silently dropped. ### Step 6: Return — Never Write @@ -205,7 +205,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. 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 d761aaf8..97907240 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,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -133,7 +133,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **modifies files** — it creates, activates, deactivates, and removes feature flag code and configuration. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 c110318c..9adde34d 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md @@ -115,7 +115,7 @@ For each approved context in scope: 1. **Check**: Does this context already exist as a file? 2. **Act**: If exists and no conflict was raised → leave untouched; pre-existing relationships without the 3-dimension assessment remain valid as-is (no forced migration — assessed the next time that relationship falls inside a `$scope`). -3. **Act**: If new, or an approved delta applies → create/update the context file following [bounded-context-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/bounded-context-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: If new, or an approved delta applies → create/update the context file following [bounded-context-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/bounded-context-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Fill all template sections: Type, Subdomains Covered, Business Scope, Relationships (with the 3-dimension assessment per relationship), Integration Patterns, Data Ownership, Team Alignment, Ubiquitous Language, Quality Attributes, Encapsulated Knowledge, Change Vectors. - File path: `adoption/tech/boundedcontext/[kebab-case-name].md` 4. **Verify**: File created/updated and parseable. Entries outside `$scope` are untouched. @@ -153,7 +153,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -164,7 +164,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **creates/updates adoption files** — not PM tool issues. Bounded contexts are design artifacts. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 1aafb820..10b98362 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md @@ -104,7 +104,7 @@ For each approved subdomain in scope: 1. **Check**: Does this subdomain already exist as a file? 2. **Act**: If exists and no conflict was raised → leave untouched; pre-existing entries without a `Volatility` field remain valid as-is (no forced migration — the field is added the next time this entry falls inside a `$scope`). -3. **Act**: If new, or an approved delta applies → create/update the subdomain file following [subdomain-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/subdomain-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: If new, or an approved delta applies → create/update the subdomain file following [subdomain-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/subdomain-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Fill all template sections: Classification, Volatility, Business Purpose, Key Capabilities, Strategic Importance, Complexity Assessment, Data Ownership, Dependencies, Team Recommendations, Implementation Priority. - File path: `adoption/product/subdomain/[kebab-case-name].md` 4. **Verify**: File created/updated and parseable. Entries outside `$scope` are untouched. @@ -141,7 +141,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -151,7 +151,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **creates/updates adoption files** — not PM tool issues. Subdomains are design artifacts. -- **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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/publish-pr/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/publish-pr/SKILL.md index 04643945..c0c56e1c 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/publish-pr/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/publish-pr/SKILL.md @@ -67,7 +67,7 @@ Each phase follows the **check → skip → act → verify** pattern. Phases run ### Phase 3: Compose the PR Body (AC3) -1. **Act**: Read the [pr-template](../../../.pair/knowledge/guidelines/collaboration/templates/pr-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md); the same resolution applies to the commit and branch templates referenced above). Fill the always-applicable sections from the handoff/story: +1. **Act**: Read the [pr-template](../../../.pair/knowledge/guidelines/collaboration/templates/pr-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md); the same resolution applies to the commit and branch templates referenced above). Fill the always-applicable sections from the handoff/story: - **Title**: `[#] : ` (`` from commit-format / story type). - **Summary** (What Changed + Why) from the story statement and the handoff's decisions. - **Story Context**: link the story issue and list AC coverage. @@ -130,7 +130,7 @@ On HALT: report the blocker, propose resolution, make no PR side effects. ## Graceful Degradation -See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-degradation.md) (guideline/template missing → minimal structure; PM tool inaccessible → do the PR, warn on the board step) for the standard scenarios. Additional cases: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (guideline/template missing → minimal structure; PM tool inaccessible → do the PR, warn on the board step) for the standard scenarios. Additional cases: - **No `## Merge Strategy` section**: default to `squash` + the commit template, base `main` — the zero-configuration default, not a degradation (AC2). Consistent with the merge consumers, which also default to `squash`. - **No `code-host` declared**: code host = PM tool (single-tool; AC4 still satisfied in the degraded shape). @@ -141,7 +141,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **creates git-host artifacts** (a pushed branch, one PR) and updates board state — it does not modify source files and never merges. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invocation detects the existing PR and updates it in place; re-runs the gate (fast if already green); re-parses the handoff. Never a duplicate PR. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). Re-invocation detects the existing PR and updates it in place; re-runs the gate (fast if already green); re-parses the handoff. Never a duplicate PR. - Tag propagation is a **copy**; the authoritative classification is (re)done in `/review` (G6). - The gate here is a local pre-flight only — CI remains authoritative (#210). - The handoff/checkpoint is the input contract (see the [checkpoint template](../../../.pair/knowledge/guidelines/collaboration/templates/checkpoint-template.md)); it is consumed here, never loaded as ambient context elsewhere. 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 0778b12d..aa727e1e 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md @@ -88,7 +88,7 @@ A domain decision only becomes a DDR if it meets **all three** criteria. This is 1. **Check**: Does [adoption/tech/adr/](../../../.pair/adoption/tech/adr/) directory exist? 2. **Act**: If not, create it. 3. **Check**: Determine the next sequence number — scan existing `adr-NNN-*.md` files, take the highest `NNN`, increment by 1 (zero-padded to 3 digits). If none exist, start at `001`. -4. **Act**: Create (or update) the ADR file at [adoption/tech/adr/](../../../.pair/adoption/tech/adr/)`adr-NNN-.md` following the standalone [ADR template](../../../.pair/knowledge/guidelines/collaboration/templates/adr-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md); the same applies to the ADL, DDR, and analysis-log templates below). Fill in all sections: Status, Date, Context, Options Considered, Decision, Consequences, and Adoption Impact. +4. **Act**: Create (or update) the ADR file at [adoption/tech/adr/](../../../.pair/adoption/tech/adr/)`adr-NNN-.md` following the standalone [ADR template](../../../.pair/knowledge/guidelines/collaboration/templates/adr-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md); the same applies to the ADL, DDR, and analysis-log templates below). Fill in all sections: Status, Date, Context, Options Considered, Decision, Consequences, and Adoption Impact. 5. **Verify**: ADR file exists with complete content following the template structure, and sequential numbering is unbroken. #### If `non-architectural` → ADL: @@ -236,7 +236,7 @@ When invoked **independently**: ## Graceful Degradation -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): +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. 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 a98ea436..3decb229 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md @@ -89,7 +89,7 @@ Configure CI/CD quality gates for the project. Reads quality assurance guideline > > Accept this configuration? -3. **Act — tiering opt-in** (per the [guided/quick setup convention](../../../.pair/knowledge/skill-conventions/guided-quick-setup.md), default **No**): the CI pipeline mode is one input resolved like any other — full-suite (default) vs risk-tier-scoped (opt-in). +3. **Act — tiering opt-in** (per the [guided/quick setup convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/guided-quick-setup.md), default **No**): the CI pipeline mode is one input resolved like any other — full-suite (default) vs risk-tier-scoped (opt-in). - **Guided mode** (interactive/TTY) — ask **one** question, pre-filled with the default: > Enable risk-tier-scoped pre-merge checks? This runs *lighter* checks on lower-risk PRs (a 🟢 PR skips integration/E2E) instead of the full suite on every PR — faster, but with less verification on low-risk changes. **[default: No — run the full suite on every PR]** @@ -174,7 +174,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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 no CI/CD platform is detectable, document gate commands for manual execution and skip pipeline file generation. @@ -186,7 +186,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - **Full checks are the default; risk-tier reduction is opt-in** (ADL 2026-07-20): unless the project sets `Pre-merge tiering: enabled` in way-of-working.md (Step 3.3 opt-in), the generated pipeline runs the **full suite on every PR** — the safe, pre-tiering behavior. Tiering only *reduces* checks on lower-risk PRs, so it must be enabled explicitly. - **When tiering is enabled, the generated pipeline reads classification tags only, never classifies** (D18): tier criteria live in [quality-model.md](../../../.pair/knowledge/guidelines/quality-assurance/quality-model.md) §3/§4; the pipeline is the deterministic Automation layer that projects the matrix from the PR's `risk:*` tag. Untagged ⇒ 🔴 (fail-safe). See [tier-aware-pipeline.md](../../../.pair/knowledge/guidelines/infrastructure/cicd-strategy/tier-aware-pipeline.md). - **Secret scanning is CI config, not a judgment call** (D24, anti-complexity): this skill provisions the job mechanically; it never evaluates whether a diff contains a secret itself — that is gitleaks' (or the adopted scanner's) job at runtime, with no LLM in the loop. `/assess-security` never re-implements this — see that skill's own Notes. -- **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 is always resolved by asking first (see Edge Cases above). +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 is always resolved by asking first (see Edge Cases above). - 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 575ead74..8d2c6446 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md @@ -138,7 +138,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/guidelines/technical-standards/ai-development/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). 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 466ca11b..38e255da 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md @@ -156,7 +156,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 the codebase is empty or no code changes to check, report all areas as `CONFORMANT` (nothing to violate). @@ -165,6 +165,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - 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** — 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. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 4e055a1c..3eb64e20 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md @@ -140,7 +140,7 @@ When invoked **independently**: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 the canonical [definition-of-ready-and-done.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/definition-of-ready-and-done.md) is not found, fall back to the extended `definition-of-done.md` checklist alone (never an empty checklist). 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 8f8f2365..c15c9bdf 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md @@ -139,7 +139,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 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." 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 43614069..b604403a 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md @@ -44,7 +44,7 @@ Create or update issues in the adopted PM tool. Template-driven: reads the type- ### Step 3: Load Template -1. **Check**: Resolve the template path for `$type` **override-first** — see [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md) (adoption `.pair/adoption/tech/templates/-template.md` wins over the KB default below): +1. **Check**: Resolve the template path for `$type` **override-first** — see [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md) (adoption `.pair/adoption/tech/templates/-template.md` wins over the KB default below): - `story` → [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) - `task` → [task-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/task-template.md) - `epic` → [epic-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/epic-template.md) @@ -190,12 +190,12 @@ When composed by `/plan-initiatives`: When composed by `/plan-epics`: -- **Input**: `/plan-epics` invokes `/write-issue` with `$type: epic`, `$content` containing the epic data, and `$parent` linking to the parent initiative. For an `EXTEND` triage outcome (see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)), it instead passes `$id` of the matched epic and `$content` as the matched epic's current full body with the additional scope already merged in by the caller — `/write-issue` overwrites the body as-is, it does not merge. +- **Input**: `/plan-epics` invokes `/write-issue` with `$type: epic`, `$content` containing the epic data, and `$parent` linking to the parent initiative. For an `EXTEND` triage outcome (see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)), it instead passes `$id` of the matched epic and `$content` as the matched epic's current full body with the additional scope already merged in by the caller — `/write-issue` overwrites the body as-is, it does not merge. - **Output**: Returns the issue identifier. `/plan-epics` uses it for linking stories. When composed by `/plan-stories`: -- **Input**: `/plan-stories` invokes `/write-issue` with `$type: story`, `$content` containing the story data, and `$parent` linking to the parent epic. For an `EXTEND` triage outcome (see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)), it instead passes `$id` of the matched story and `$content` as the matched story's current full body with the additional scope already merged in by the caller — `/write-issue` overwrites the body as-is, it does not merge. +- **Input**: `/plan-stories` invokes `/write-issue` with `$type: story`, `$content` containing the story data, and `$parent` linking to the parent epic. For an `EXTEND` triage outcome (see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)), it instead passes `$id` of the matched story and `$content` as the matched story's current full body with the additional scope already merged in by the caller — `/write-issue` overwrites the body as-is, it does not merge. - **Output**: Returns the issue identifier. `/plan-stories` uses it for status tracking. When invoked **independently**: @@ -220,7 +220,7 @@ This skill supports `story`, `task`, `epic`, and `initiative` types. Adding a ne ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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). @@ -229,7 +229,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **modifies PM tool state** — it creates and updates issues. -- 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. +- No PM tool fallback: if the adopted tool fails, the skill HALTs. **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 80861833..18f72ea5 100644 --- a/packages/knowledge-hub/dataset/.skills/next/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/next/SKILL.md @@ -206,7 +206,7 @@ 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: +See [graceful degradation](../../.pair/knowledge/guidelines/technical-standards/ai-development/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: - **Argument edge cases** (see Step 0): `--root` not found → HALT, no action; `--root` resolves to a Done issue → report and exit; `--filter` (or the subtree) matches nothing → report `no matching issues` and exit cleanly (an empty result is not an error). - If a suggested skill is not installed, tell the user which skill is needed and where to find it. diff --git a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md index 0cb41e99..e24a79fb 100644 --- a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md @@ -253,7 +253,7 @@ On HALT: report the blocker clearly, propose resolution, wait for developer. ## Idempotent Re-invocation -See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/bootstrap` on a partially completed project is safe and expected — per-phase: +See [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -266,7 +266,7 @@ 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): +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/graceful-degradation.md) (optional skill not installed → skip that phase/step with a warning, never blocks) and [record-decision contract](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 (a required dependency, not optional). Suggest creating PRD manually using how-to-01. @@ -278,6 +278,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes -- The developer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). +- The developer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 3feabf43..d4335b68 100644 --- a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md @@ -53,7 +53,7 @@ The opening phase re-reads the checkpoint so an interrupted story resumes exactl 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 — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md). +3. **Act**: Read the story from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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**. @@ -233,7 +233,7 @@ Follow the TDD discipline rules strictly, and the [Design Rules](../../../.pair/ **This confirmation is required for EVERY task** — commit-per-task exists precisely to give the developer a checkpoint between tasks. 4. **Verify**: Developer confirms. If changes needed → apply changes, re-run quality (Step 2.7), ask again. -5. **Act**: Stage and commit following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +5. **Act**: Stage and commit following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): ```text [#] : @@ -352,7 +352,7 @@ On HALT: report the blocker clearly, propose resolution, wait for developer. ## Idempotent Re-invocation -See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/implement` on a partially completed story is safe and expected — per-step: +See [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). Re-invoking `/implement` on a partially completed story is safe and expected — per-step: 1. **Checkpoint**: the opening-phase resume probe (Step 0.0) reads the checkpoint and jumps to the first pending task — never repeating completed tasks. When `/checkpoint` is absent, the git+PM resume below applies. 2. **Branch**: detects existing branch, switches to it. @@ -366,7 +366,7 @@ The skill resumes from the first incomplete step — never re-does completed wor ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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: - **Subagent spawning unavailable**: take the degraded inline path (Step 3.3) — checkpoint still written, `/publish-pr` composed inline, degradation noted in the output. Never skip the checkpoint/PR split. - **`/checkpoint` not installed**: skip the resume probe and the write step; resume from git+PM state (Idempotent Re-invocation) and synthesize the handoff inline for `/publish-pr`. @@ -380,6 +380,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - This skill **modifies files and creates git artifacts** (branches, commits) and **writes the checkpoint**. The PR itself is created/updated by the composed `/publish-pr` (in the subagent, or inline when degraded) — implement never re-implements PR creation. - The **subagent's prompt is the handoff only** — the checkpoint, nothing from this session. Anonymous, no named role (mechanical isolation, D23); a skill cannot `/clear` its own context (D7), so the subagent provides the clean-context reset. - Task iteration is sequential — each task completes its full cycle before the next begins. -- The developer can stop between tasks; re-invoke to resume — the opening-phase resume probe (Step 0.0) reads the checkpoint (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). +- The developer can stop between tasks; re-invoke to resume — the opening-phase resume probe (Step 0.0) reads the checkpoint (see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/implement/post-review-merge.md b/packages/knowledge-hub/dataset/.skills/process/implement/post-review-merge.md index 19f3c465..f09516c6 100644 --- a/packages/knowledge-hub/dataset/.skills/process/implement/post-review-merge.md +++ b/packages/knowledge-hub/dataset/.skills/process/implement/post-review-merge.md @@ -12,7 +12,7 @@ Disclosed from [SKILL.md](SKILL.md) Phase 4 — only reached when `/implement` i 1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) for merge strategy (squash, merge, rebase). 2. **Act**: Draft the final commit message: - - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)). + - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)). - **If merge or rebase**: use the default merge/rebase message. 3. **Act** (BLOCKING): Present the commit message to the developer for confirmation: 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 f3389da3..319b9445 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md @@ -52,7 +52,7 @@ Transform strategic initiatives into comprehensive epic breakdowns. Each epic de ### Step 2: Build Existing Epic Registry 1. **Check**: Query PM tool for existing epic issues linked to the selected initiative — **including closed/Done items** (the closed-item triage rule in Step 3 depends on them being in the registry; many PM-tool queries default to open-only). -2. **Act**: Build a registry of existing epics, keyed for matching (idempotency key — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)): +2. **Act**: Build a registry of existing epics, keyed for matching (idempotency key — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)): ```text EXISTING EPICS: @@ -74,7 +74,7 @@ Transform strategic initiatives into comprehensive epic breakdowns. Each epic de - **Value-driven grouping**: natural feature groupings following user workflows. - **Sequential dependencies**: foundation-first, user journey progression. - **Duration sizing**: 2-4 sprints per epic with clear completion criteria. -3. **Act**: Triage each candidate epic against the Step 2 registry — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md) for the matching shape (idempotency key, EXTEND-vs-CREATE threshold, ambiguous-match and closed-item handling). **This skill's parent scope**: the selected initiative. First, check each candidate's idempotency key against the registry: an exact match to an existing **open** epic is `ALREADY EXISTS #ID` (skip) — per to-issues-triage.md's Skip step, not a triage decision. For every remaining candidate, classify `EXTEND #ID` or `CREATE` — or, if ambiguous (per to-issues-triage.md), present it as a question with a recommendation instead of silently picking one side. Present the triage proposal to developer: +3. **Act**: Triage each candidate epic against the Step 2 registry — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md) for the matching shape (idempotency key, EXTEND-vs-CREATE threshold, ambiguous-match and closed-item handling). **This skill's parent scope**: the selected initiative. First, check each candidate's idempotency key against the registry: an exact match to an existing **open** epic is `ALREADY EXISTS #ID` (skip) — per to-issues-triage.md's Skip step, not a triage decision. For every remaining candidate, classify `EXTEND #ID` or `CREATE` — or, if ambiguous (per to-issues-triage.md), present it as a question with a recommendation instead of silently picking one side. Present the triage proposal to developer: > Epic breakdown for Initiative `#[ID]: [Title]`: > @@ -103,7 +103,7 @@ Process epics sequentially (Epic 0 first if needed), per its Step 3 proposal: > Epic `[Title]` already exists (#ID). Skipping. -3. **Act**: Draft the epic following [epic-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/epic-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: Draft the epic following [epic-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/epic-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Fill template sections: Epic Statement, Business Value, Solution Overview, Epic Breakdown, Technical Considerations. - Present to developer for validation. 4. **Act**: Compose `/write-issue` per the confirmed proposal: @@ -142,7 +142,7 @@ EPICS COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -150,6 +150,6 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d ## Notes - This skill **modifies PM tool state** — creates and extends epic issues linked to initiatives. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md) and [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md). This skill's check: exact idempotency-key match is proposed `ALREADY EXISTS #ID` (skip) at triage time, before any write (Step 3) — Step 4 only executes the confirmed proposal; substantial-overlap match proposes EXTEND instead of a duplicate CREATE (Step 3) — re-running the same candidate tree never duplicates. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) and [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md). This skill's check: exact idempotency-key match is proposed `ALREADY EXISTS #ID` (skip) at triage time, before any write (Step 3) — Step 4 only executes the confirmed proposal; substantial-overlap match proposes EXTEND instead of a duplicate CREATE (Step 3) — re-running the same candidate tree never duplicates. - 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 2ea63fe3..0649a58f 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md @@ -90,7 +90,7 @@ Process initiatives by priority (P0 → P1 → P2). For each initiative: > Initiative `[Title]` already exists (#ID). Skipping. -3. **Act**: Draft the initiative following the [initiative-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/initiative-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: Draft the initiative following the [initiative-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/initiative-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Fill template sections with PRD-derived content. - Include business rationale, scope, success metrics, risk assessment, timeline. - Present to developer for validation. @@ -134,12 +134,12 @@ INITIATIVES COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: detects existing initiatives by title matching and skips them. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 c8b8f81a..e2f6d2b9 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md @@ -55,7 +55,7 @@ Transform epics into user stories through vertical slicing, INVEST validation, a ### Step 2: Build Existing Story Registry 1. **Check**: Query PM tool for existing story issues linked to the selected epic — **including closed/Done items** (the closed-item triage rule in Step 3 depends on them being in the registry; many PM-tool queries default to open-only). -2. **Act**: Build a registry of existing stories, keyed for matching (idempotency key — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)): +2. **Act**: Build a registry of existing stories, keyed for matching (idempotency key — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)): ```text EXISTING STORIES: @@ -72,8 +72,8 @@ Transform epics into user stories through vertical slicing, INVEST validation, a - **CRUD operations**: create, read, update, delete patterns. - **Business rules**: different scenarios and conditions. - **User roles**: admin, member, guest variations. -2. **Act**: Apply vertical slicing — every story must deliver end-to-end user value with visible UI manifestation. This rule governs CREATE candidates only — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md)'s per-skill-delta note. -3. **Act**: Triage each candidate story against the Step 2 registry — see [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md) for the matching shape (idempotency key, EXTEND-vs-CREATE threshold, ambiguous-match and closed-item handling). **This skill's parent scope**: the selected epic. First, check each candidate's idempotency key against the registry: an exact match to an existing **open** story is `ALREADY EXISTS #ID` (skip) — per to-issues-triage.md's Skip step, not a triage decision. For every remaining candidate, classify `EXTEND #ID` or `CREATE` — or, if ambiguous (per to-issues-triage.md), present it as a question with a recommendation instead of silently picking one side. Present the triage proposal to developer: +2. **Act**: Apply vertical slicing — every story must deliver end-to-end user value with visible UI manifestation. This rule governs CREATE candidates only — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md)'s per-skill-delta note. +3. **Act**: Triage each candidate story against the Step 2 registry — see [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md) for the matching shape (idempotency key, EXTEND-vs-CREATE threshold, ambiguous-match and closed-item handling). **This skill's parent scope**: the selected epic. First, check each candidate's idempotency key against the registry: an exact match to an existing **open** story is `ALREADY EXISTS #ID` (skip) — per to-issues-triage.md's Skip step, not a triage decision. For every remaining candidate, classify `EXTEND #ID` or `CREATE` — or, if ambiguous (per to-issues-triage.md), present it as a question with a recommendation instead of silently picking one side. Present the triage proposal to developer: > Story candidates for Epic `#[ID]: [Title]`: > @@ -94,7 +94,7 @@ For each approved story, per its Step 3 proposal: > Story `[Title]` already exists (#ID). Skipping. -3. **Act**: Define story scope using the Initial Breakdown section of [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +3. **Act**: Define story scope using the Initial Breakdown section of [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Story statement (As a / I want / So that). - Rough scope boundaries with expected uncertainty. - Initial sizing: XS(1), S(2), M(3), L(5), XL(8). @@ -148,13 +148,13 @@ STORIES COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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 and extends story issues linked to epics. -- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md) and [to-issues-triage.md](../../../.pair/knowledge/skill-conventions/to-issues-triage.md). This skill's check: exact idempotency-key match is proposed `ALREADY EXISTS #ID` (skip) at triage time, before any write (Step 3) — Step 4 only executes the confirmed proposal; substantial-overlap match proposes EXTEND instead of a duplicate CREATE (Step 3) — re-running the same candidate tree never duplicates. +- **Idempotent** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md) and [to-issues-triage.md](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/to-issues-triage.md). This skill's check: exact idempotency-key match is proposed `ALREADY EXISTS #ID` (skip) at triage time, before any write (Step 3) — Step 4 only executes the confirmed proposal; substantial-overlap match proposes EXTEND instead of a duplicate CREATE (Step 3) — re-running the same candidate tree never duplicates. - Stories at breakdown stage are rough planning units — detailed requirements are added during `/refine-story`. - INVEST validation is mandatory for CREATE candidates — stories failing INVEST must be reworked before creation. EXTEND candidates re-validate INVEST for the merged scope (Step 4). 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 77350147..2b9792fd 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md @@ -90,7 +90,7 @@ Transform a refined user story into specific, actionable implementation tasks. T For each task (skipping tasks that already exist in the story body): -1. **Act**: Define the task following the [task-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/task-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +1. **Act**: Define the task following the [task-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/task-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - Task Information (ID, priority, hours, bounded context) - Summary and type - Description with implementation context @@ -157,13 +157,13 @@ TASK BREAKDOWN COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. -- **Idempotent (task-level)** — see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). This skill's check: re-invoking on a story with partial tasks adds only the missing ones (the caller composes the full updated body; write-issue overwrites it). +- **Idempotent (task-level)** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md). This skill's check: re-invoking on a story with partial tasks adds only the missing ones (the caller composes the full updated body; write-issue overwrites it). - 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 951761d6..4f63bc0a 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 (single Draft→Ready) -Transform a user story from rough breakdown (Draft) into a development-ready specification (Ready). This is **THE single Draft→Ready path** — no separate "make-ready" skill exists and none is ever born (R3.12, D24); refinement IS the transition (canonical-states.md). **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, an already-Ready story is confirmed and exits. +Transform a user story from rough breakdown (Draft) into a development-ready specification (Ready). This is **THE single Draft→Ready path** — no separate "make-ready" skill exists and none is ever born (R3.12, D24); refinement IS the transition (canonical-states.md). **Section-level idempotency** — see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/idempotency.md): each refinement section is checked before acting; partial refinements resume from the first missing section, an already-Ready story is confirmed and exits. ## Composed Skills @@ -138,7 +138,7 @@ Transform a user story from rough breakdown (Draft) into a development-ready spe ### Step 5: Documentation and PM Tool Update -1. **Act**: Assemble the complete refined story body using the [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)) Refined template: +1. **Act**: Assemble the complete refined story body using the [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)) Refined template: - **Functional sections first**: Story Statement → Epic Context → Classification (the Step 3b matrix) → Acceptance Criteria → Definition of Done → Story Sizing → Dependencies → Validation → Notes. - **Technical sections last**: Technical Analysis → (Task Breakdown added later by `/plan-tasks`). 2. **Act**: Compose `/write-issue` with: @@ -189,7 +189,7 @@ STORY REFINEMENT COMPLETE: ## Graceful Degradation -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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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: - **`/grill` not installed** (Phase 0): warn and skip the sync; the per-step human-judgment approval gates in Steps 2–4 remain the alignment mechanism — refinement still completes. - **`/map-subdomains` / `/map-contexts` not installed, or no domain artifacts** (Steps 2–3): the functional and technical analysis sections are still produced; domain placement and touched-context mapping are skipped with a note, and the coupling dimension is "not assessed" (never a HALT). diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index 8c6fc813..a4425d85 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -53,7 +53,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 — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/skill-conventions/way-of-working-pm-resolution.md): +3. **Act**: Read PR from the PM tool — resolution: see [way-of-working / PM-tool resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md): - PR metadata (author, branch, target, status) - Changed files and diff - PR description and linked story @@ -191,7 +191,7 @@ Run the procedure for the level determined in Step 3.1 — see [degradation-leve ### Step 5.1: Compile Review Report -1. **Act**: Compile all findings into a review report following the [code-review-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/code-review-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +1. **Act**: Compile all findings into a review report following the [code-review-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/code-review-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): - **Review Information**: PR number, author, reviewer, date, story, review type - **Review Summary**: overall assessment, key changes, business value - **Code Review Checklist**: functionality, code quality, technical standards (from Phase 2) @@ -271,7 +271,7 @@ On HALT: report the blocker, compose the resolution skill if available, wait for ## Idempotent Re-invocation -See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md). Re-invoking `/review` on a partially reviewed PR is safe — per-phase: +See [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -282,7 +282,7 @@ See [idempotency convention](../../../.pair/knowledge/skill-conventions/idempote ## 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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. @@ -299,7 +299,7 @@ See [graceful degradation](../../../.pair/knowledge/skill-conventions/graceful-d - 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 (see [idempotency convention](../../../.pair/knowledge/skill-conventions/idempotency.md)). +- The reviewer can stop between phases; re-invoke to resume (see [idempotency convention](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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/review/merge-and-cascade.md b/packages/knowledge-hub/dataset/.skills/process/review/merge-and-cascade.md index 827670d5..259360a0 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/merge-and-cascade.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/merge-and-cascade.md @@ -11,7 +11,7 @@ Disclosed from [SKILL.md](SKILL.md) Phase 6 — only reached when the reviewer p ### Step 6.2: Prepare Merge Commit -1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/skill-conventions/template-resolution.md)): +1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md) (resolve override-first — [template resolution](../../../.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/template-resolution.md)): ```text [#] feat: 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 2bbe58c8..2e06fb00 100644 --- a/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md @@ -180,7 +180,7 @@ 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: +See [graceful degradation](../../../.pair/knowledge/guidelines/technical-standards/ai-development/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." diff --git a/packages/knowledge-hub/src/conformance/template-resolution.test.ts b/packages/knowledge-hub/src/conformance/template-resolution.test.ts index e5143e78..b5496747 100644 --- a/packages/knowledge-hub/src/conformance/template-resolution.test.ts +++ b/packages/knowledge-hub/src/conformance/template-resolution.test.ts @@ -10,7 +10,10 @@ import { collectSkillFiles, collectSkillMarkdownFiles } from '../tools/skills-co // `template-resolution.md` convention — not by hardcoding the KB path alone. const DATASET_SKILLS = join(__dirname, '../../dataset/.skills') -const CONVENTIONS = join(__dirname, '../../dataset/.pair/knowledge/skill-conventions') +const CONVENTIONS = join( + __dirname, + '../../dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions', +) const MIRROR = join(__dirname, '../../../../.claude/skills') // The guidelines corpus (dataset source + generated repo root) — the skills scan // above never sees it, yet a template use-site lives here (context-map-maintenance.md, diff --git a/packages/knowledge-hub/src/conformance/to-issues-triage.test.ts b/packages/knowledge-hub/src/conformance/to-issues-triage.test.ts index ca021cb1..b9925333 100644 --- a/packages/knowledge-hub/src/conformance/to-issues-triage.test.ts +++ b/packages/knowledge-hub/src/conformance/to-issues-triage.test.ts @@ -7,7 +7,10 @@ import { join } from 'path' // exists-then-skip check, per the shared to-issues-triage.md convention. const DATASET_SKILLS = join(__dirname, '../../dataset/.skills/process') -const DATASET_CONVENTIONS = join(__dirname, '../../dataset/.pair/knowledge/skill-conventions') +const DATASET_CONVENTIONS = join( + __dirname, + '../../dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions', +) const MIRROR = join(__dirname, '../../../../.claude/skills') const CONVENTION = readFileSync(join(DATASET_CONVENTIONS, 'to-issues-triage.md'), 'utf-8')