[#313] docs: skill authoring effectiveness standard (task T2)

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

@@ -17,7 +17,7 @@ Evaluate and recommend AI development tools: AI assistants, MCP integrations, AI
 
 ## Composed Skills
 
-This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
+**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
 
 ## Proposal Target
 
@@ -97,7 +97,7 @@ The rendered adoption content is destined for this section — the caller writes
    - MCP integrations if applicable
    - AI-specific SDKs and libraries with versions
    - Scope strictly to the AI section so the caller's write preserves all other sections (core, testing)
-2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.**
+2. **Verify**: The rendered `content` and its `target` are ready to emit.
 
 ### Step 5: Emit Proposal
 

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

@@ -17,7 +17,7 @@ Evaluate and recommend the system architecture pattern. Follows the resolution c
 
 ## Composed Skills
 
-This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
+**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
 
 ## Proposal Target
 
@@ -98,7 +98,7 @@ The rendered adoption content is destined for this file — the caller writes it
    - Concise, prescriptive statements (what IS adopted, not options)
    - Reference guidelines for detailed rationale
    - Scope the content to this skill's owned section so the caller's write preserves other sections
-2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.**
+2. **Verify**: The rendered `content` and its `target` are ready to emit.
 
 ### Step 5: Emit Proposal
 
@@ -107,7 +107,7 @@ The rendered adoption content is destined for this file — the caller writes it
    - `target`: [adoption/tech/architecture.md](../../../.pair/adoption/tech/architecture.md) (owned section)
    - `decision-metadata`: `$type: architectural`, `$topic: architecture-pattern`, `$summary: "[Pattern] adopted as system architecture"`
    - plus the human-facing report (see Output Format)
-2. **Verify**: Proposal emitted. Persistence — writing `content` to `target` and recording the ADR — is performed by the caller via `/pair-capability-record-decision(content, target, decision-metadata)`, never by this skill.
+2. **Verify**: Proposal emitted. Persistence is performed by the caller via `/pair-capability-record-decision(content, target, decision-metadata)`, never by this skill.
 
 ## Output Format
 
@@ -132,7 +132,7 @@ When composed by `/pair-process-bootstrap`:
 
 When invoked **independently**:
 
-- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits the changes.
+- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits.
 
 ## Edge Cases
 

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

@@ -45,7 +45,7 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p
    - Size metrics: lines of code, function length, class/module size, file size
    - Quality metrics: test coverage, code duplication, maintainability index
    - Thresholds per metric (e.g., cyclomatic complexity 1-5 = simple, 16+ = refactor needed)
-2. **Verify**: Guidelines loaded. If not found, use built-in thresholds.
+2. **Verify**: Guidelines loaded.
 
 ### Step 3: Collect Metrics
 
@@ -149,7 +149,6 @@ When composed by `/pair-process-review`:
 When invoked **independently**:
 
 - Full interactive flow. Developer receives the report and decides on improvement actions.
-- This skill is **read-only** — it inspects code and runs tests (coverage) but does not modify files.
 
 ## Graceful Degradation
 
@@ -162,7 +161,6 @@ When invoked **independently**:
 
 - This skill is **read-only / output-only** — it inspects code, runs coverage (via existing test commands), but never modifies files, adoption, or the PM tool. A finding worth tracking is promoted deliberately to the backlog via `/pair-capability-write-issue` (a manual, selective act) — never auto-created.
 - **Idempotent**: re-invocation checks staleness of existing report. If codebase unchanged → confirms existing report. If changed → re-assesses only.
-- **Resolution cascade**: Path A (existing recent report) → Path B (full assessment). Follows the same cascade pattern as other assess-* skills.
 - 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 assessment 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 assessment but the component metrics offer more actionable insights.

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

@@ -7,7 +7,7 @@ author: Foomakers
 
 # /pair-capability-assess-debt — Technical Debt Assessment
 
-Detect, categorize, and prioritize technical debt items. Applies the prioritization framework from [technical-debt.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/technical-debt.md) guidelines. Produces a debt report with categorized items, severity, impact/effort scoring, and remediation recommendations. **Output-only**: this skill returns a report — it writes no files, creates no PM-tool items, and there is **no `$mode:scan`** and **no auto-conversion** of debt into backlog cards. Technical debt **never blocks a PR** (R7.2).
+Detect, categorize, and prioritize technical debt items. Applies the prioritization framework from [technical-debt.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/technical-debt.md) guidelines. Produces a debt report with categorized items, severity, impact/effort scoring, and remediation recommendations. **Output-only**: this skill returns a report — it writes no files, creates no PM-tool items, and there is **no `$mode:scan`** and **no auto-conversion** of debt into backlog cards. Technical debt **never blocks a PR**.
 
 ## Arguments
 
@@ -18,7 +18,7 @@ Detect, categorize, and prioritize technical debt items. Applies the prioritizat
 
 ## Composed Skills
 
-This skill is **output-only** — it composes no skill and writes no files. It never auto-creates tech-debt items. A debt item worth scheduling is promoted **deliberately** to the backlog by a human/agent via `/pair-capability-write-issue` with the `tech-debt` label (see [Composition Interface](#composition-interface)) — a manual, selective act, never a 100% auto-conversion.
+This skill is **output-only** — it composes no skill and writes no files. No auto-creation of tech-debt items. A debt item worth scheduling is promoted **deliberately** to the backlog by a human/agent via `/pair-capability-write-issue` with the `tech-debt` label (see [Composition Interface](#composition-interface)) — a manual, selective act, never a 100% auto-conversion.
 
 ## Algorithm
 
@@ -175,14 +175,13 @@ When composed by `/pair-process-review`:
 
 - **Input**: /pair-process-review invokes `/pair-capability-assess-debt` during the completeness phase (Phase 4).
 - **Output**: Returns the debt assessment report. /pair-process-review incorporates findings into review output (the Tech Debt section).
-  - Debt items are **informational** — they do **not** HALT the review and **never** block the PR (R7.2).
+  - Debt items are **informational** — they do **not** HALT the review and **never** block the PR.
   - /pair-process-review does **not** auto-create tech-debt issues. Items worth tracking are promoted deliberately (after review) via `/pair-capability-write-issue` with the `tech-debt` label.
 
 When invoked **independently**:
 
 - Full interactive flow. Scan codebase or specified scope for debt.
 - Report findings with categorization and prioritization.
-- This skill is **output-only** — it inspects code but writes no files, creates no issues, and blocks nothing. Promotion to the backlog is a separate, deliberate `/pair-capability-write-issue` action.
 
 ## Graceful Degradation
 
@@ -193,9 +192,6 @@ When invoked **independently**:
 
 ## Notes
 
-- This skill **replaces the stub implementation** from [#100](https://github.com/foomakers/pair/issues/100). Full categorization, prioritization formula, and remediation recommendations are now included.
-- **Resolution cascade**: Path A (pre-identified item) → Path B (existing assessment) → Path C (full scan). Follows the same pattern as other assess-* skills.
 - **Idempotent**: re-invocation on an already-assessed codebase confirms the existing assessment. Re-assessment only on explicit developer request.
-- **Output-only** — this skill inspects code but never modifies files, adoption, or the PM tool. There is no `$mode:scan` and no auto-creation of tech-debt items (R7.2). Debt is surfaced in the report; promotion to the backlog is a deliberate `/pair-capability-write-issue` act with the `tech-debt` label.
 - Prioritization formula `Impact × (6 - Effort)` favors quick wins: high-impact items with low effort get the highest scores.
 - Debt is contextual — the same pattern may be acceptable in a prototype but unacceptable in production code. Severity assessment considers the project's maturity and risk tolerance.

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

@@ -17,7 +17,7 @@ Evaluate and recommend infrastructure strategy: cloud provider, CI/CD pipeline,
 
 ## Composed Skills
 
-This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
+**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
 
 ## Proposal Target
 
@@ -87,7 +87,7 @@ The rendered adoption content is destined for this file — the caller writes it
 1. **Act**: Render the infrastructure.md content — the ready-to-write body for the target file:
    - Concise, prescriptive statements
    - Scope to the core infrastructure sections so the caller's write preserves the observability section (owned by /pair-capability-assess-observability)
-2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.**
+2. **Verify**: The rendered `content` and its `target` are ready to emit.
 
 ### Step 5: Emit Proposal
 

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

@@ -17,7 +17,7 @@ Evaluate and recommend the development methodology: Scrum, Kanban, Lean, Waterfa
 
 ## Composed Skills
 
-This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
+**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
 
 ## Proposal Target
 
@@ -92,7 +92,7 @@ The rendered adoption content is destined for this section — the caller writes
    - Methodology name and key practices
    - Development cycle description (iterations, flow, etc.)
    - Scope strictly to the methodology section so the caller's write preserves all other sections (quality gates, PM tool, etc.)
-2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.**
+2. **Verify**: The rendered `content` and its `target` are ready to emit.
 
 ### Step 5: Emit Proposal
 

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

@@ -17,7 +17,7 @@ Evaluate and recommend the observability strategy: monitoring platform, logging
 
 ## Composed Skills
 
-This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
+**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
 
 ## Proposal Target
 
@@ -90,7 +90,7 @@ The rendered adoption content is destined for this section — the caller writes
 1. **Act**: Render the **observability section** content — the ready-to-write body for infrastructure.md:
    - Platform, logging, tracing, alerting decisions
    - Scope strictly to the observability section so the caller's write preserves all other sections (owned by /pair-capability-assess-infrastructure)
-2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.**
+2. **Verify**: The rendered `content` and its `target` are ready to emit.
 
 ### Step 5: Emit Proposal
 

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

@@ -95,7 +95,7 @@ The rendered adoption content is destined for this section — the caller (or `/
    - Workflow methodology integration
    - Access method (MCP, CLI, filesystem)
    - Scope strictly to the PM tool section so the caller's write preserves all other sections
-4. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.**
+4. **Verify**: The rendered `content` and its `target` are ready to emit.
 
 ### Step 5: Emit Proposal (only if /pair-capability-setup-pm not invoked)
 
@@ -148,5 +148,5 @@ When invoked **independently**:
 
 - PM tool decisions are **non-architectural** → the caller records them as an ADL.
 - **Section ownership**: this skill renders content ONLY for the PM tool section of way-of-working.md. The single adoption writer is `/pair-capability-record-decision` (or `/pair-capability-setup-pm` when it handles configuration).
-- **Delegation pattern**: /pair-capability-assess-pm decides WHICH tool, /pair-capability-setup-pm configures it. If /pair-capability-setup-pm is installed, it handles both adoption write and decision recording; assess-pm itself never writes adoption.
+- **Delegation pattern**: /pair-capability-assess-pm decides WHICH tool, /pair-capability-setup-pm configures it — handling both adoption write and decision recording when installed.
 - Educational content (tool descriptions, integration details) stays in guidelines.

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

@@ -18,7 +18,7 @@ Evaluate and recommend the technology stack: languages, frameworks, runtime, dat
 
 ## Composed Skills
 
-This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
+**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
 
 ## Proposal Target
 
@@ -171,7 +171,7 @@ Detect and evaluate unlisted dependencies. Used when `/pair-process-review` find
 
 1. **Act** (bootstrap mode): Render full tech-stack.md content with all core sections. Include version for every entry.
 2. **Act** (implementation/review mode): Render the affected-entry content for the appropriate section, scoped so the caller's write preserves all other content, including sections owned by /pair-capability-assess-testing and /pair-capability-assess-ai.
-3. **Verify**: The rendered `content` and its `target` are ready to emit. All entries have versions; section ownership respected. **This skill writes no files.**
+3. **Verify**: The rendered `content` and its `target` are ready to emit. All entries have versions; section ownership respected.
 
 ### Step 5: Emit Proposal
 
@@ -259,8 +259,6 @@ When invoked **independently**:
 
 ## Notes
 
-- **Lifecycle-spanning**: unlike other assess-* skills (primarily bootstrap), /pair-capability-assess-stack is used throughout bootstrap, implementation, and review.
 - **Tech stack as registry**: `tech-stack.md` is the registry of approved technologies. Only listed technologies are approved. Unlisted technologies detected during review trigger /pair-capability-assess-stack evaluation.
 - Stack decisions are typically **non-architectural** → the caller records them as an ADL. Exception: if a stack choice fundamentally changes the architecture (e.g. switching from monolith to microservices runtime), the caller uses ADR.
-- **Section ownership** keeps proposals non-overlapping: each assess-* skill renders only its sections; the single adoption writer is `/pair-capability-record-decision`, which preserves others on write.
 - Educational content (technology descriptions, ecosystem overview, WHY) stays in guidelines. This skill references guidelines for evaluation criteria and comparison matrices.

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

@@ -17,7 +17,7 @@ Evaluate and recommend the testing strategy: framework, pyramid distribution, co
 
 ## Composed Skills
 
-This skill is **output-only** — it composes no skill and writes no files. Persistence of the proposal is the caller's responsibility via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
+**Output-only** — composes no skill, writes no files; the caller persists via `/pair-capability-record-decision` (see [Composition Interface](#composition-interface)).
 
 ## Proposal Target
 
@@ -108,7 +108,7 @@ The rendered adoption content is destined for this section — the caller writes
    - Coverage tool and version
    - Additional testing tools with versions
    - Scope strictly to the Testing section so the caller's write preserves all other sections (core, AI, etc.)
-2. **Verify**: The rendered `content` and its `target` are ready to emit. **This skill writes no files.**
+2. **Verify**: The rendered `content` and its `target` are ready to emit.
 
 ### Step 5: Emit Proposal
 
@@ -142,7 +142,7 @@ When composed by `/pair-process-bootstrap`:
 
 When invoked **independently**:
 
-- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits the changes.
+- Full interactive flow. The skill returns the proposal; the human (or agent) persists it by composing `/pair-capability-record-decision`, then commits.
 
 ## Edge Cases
 
@@ -161,7 +161,7 @@ When invoked **independently**:
 ## Notes
 
 - Testing decisions are typically **non-architectural** → the caller records them as an ADL. Exception: if the testing strategy choice affects system structure (e.g. choosing contract testing that requires service boundaries), the caller uses ADR instead.
-- **Section ownership**: this skill renders content ONLY for the Testing section of tech-stack.md. /pair-capability-assess-stack owns core sections, /pair-capability-assess-ai owns AI section. The single adoption writer is `/pair-capability-record-decision`.
+- **Section ownership**: this skill renders content ONLY for the Testing section of tech-stack.md. The single adoption writer is `/pair-capability-record-decision`.
 - Version tracking: every testing tool includes specific version.
 - The resolution cascade IS the idempotency mechanism: if testing section is populated, assessment is already done.
 - Educational content (testing philosophy, principles, WHY) stays in guidelines. This skill references guidelines for framework comparison and strategy decisions.