From b18272d5f78384a3c8d98a94428f3e59ec291611 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 13 Jul 2026 22:34:22 +0200 Subject: [PATCH 1/2] =?UTF-8?q?[#313]=20refactor:=20skill=20naming=20taxon?= =?UTF-8?q?omy=20=E2=80=94=20analyze-*=20for=20report=20skills=20(T8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename assess-debt→analyze-debt, assess-code-quality→analyze-code-quality (dataset + .claude mirror, git mv preserves history) - New analyze-* verb = analyze+report only; vs assess-*=propose adoption choice, verify-*=conformance pass/fail - Router catalog rows+cascade (category Analysis), /review required composition, concepts doc composition example - skills-guide: new Analysis group; Verification=only 3 verify-*; manage-flags→Operational; Code Quality bucket dissolved; +checkpoint bucket; Migration Notes entry (dataset+root mirror) - skills-catalog new Analysis Capabilities section; writing-skills verb taxonomy row+rule - eval trigger-prompts family analyze-report; conformance test covers analyze-* output-only + analyze-debt no scan-mode - ADL 2026-07-13-skill-naming-verb-taxonomy; count stays 35 Refs: #313 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../SKILL.md | 8 +-- .../SKILL.md | 8 +-- .claude/skills/pair-next/SKILL.md | 6 +- .claude/skills/pair-process-review/SKILL.md | 12 ++-- .../2026-07-13-skill-naming-verb-taxonomy.md | 56 +++++++++++++++++++ .pair/knowledge/skills-guide.md | 35 +++++++++--- apps/website/content/docs/concepts/skills.mdx | 2 +- .../docs/contributing/writing-skills.mdx | 6 +- .../content/docs/reference/skills-catalog.mdx | 15 +++-- .../dataset/.pair/knowledge/skills-guide.md | 35 +++++++++--- .../SKILL.md | 8 +-- .../{assess-debt => analyze-debt}/SKILL.md | 8 +-- .../dataset/.skills/next/SKILL.md | 6 +- .../dataset/.skills/process/review/SKILL.md | 12 ++-- .../knowledge-hub/eval/trigger-prompts.json | 16 +++--- .../conformance/assess-output-only.test.ts | 48 +++++++++++----- 16 files changed, 202 insertions(+), 79 deletions(-) rename .claude/skills/{pair-capability-assess-code-quality => pair-capability-analyze-code-quality}/SKILL.md (97%) rename .claude/skills/{pair-capability-assess-debt => pair-capability-analyze-debt}/SKILL.md (97%) create mode 100644 .pair/adoption/decision-log/2026-07-13-skill-naming-verb-taxonomy.md rename packages/knowledge-hub/dataset/.skills/capability/{assess-code-quality => analyze-code-quality}/SKILL.md (97%) rename packages/knowledge-hub/dataset/.skills/capability/{assess-debt => analyze-debt}/SKILL.md (97%) diff --git a/.claude/skills/pair-capability-assess-code-quality/SKILL.md b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md similarity index 97% rename from .claude/skills/pair-capability-assess-code-quality/SKILL.md rename to .claude/skills/pair-capability-analyze-code-quality/SKILL.md index eef1080d..5fba1c8c 100644 --- a/.claude/skills/pair-capability-assess-code-quality/SKILL.md +++ b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md @@ -1,11 +1,11 @@ --- -name: pair-capability-assess-code-quality -description: "Assesses code quality using resolution cascade (Argument > Adoption > Assessment). Applies quality score formula from code-metrics guidelines. Produces quality report with complexity, size, coverage, and maintainability metrics (output-only, writes nothing). Idempotent: detects existing report, checks staleness. Invocable independently or composed by /pair-process-review." +name: pair-capability-analyze-code-quality +description: "Analyzes code quality using resolution cascade (Argument > Adoption > Assessment). Applies quality score formula from code-metrics guidelines. Produces quality report with complexity, size, coverage, and maintainability metrics (output-only, writes nothing). Idempotent: detects existing report, checks staleness. Invocable independently or composed by /pair-process-review." version: 0.5.0 author: Foomakers --- -# /pair-capability-assess-code-quality — Code Quality Assessment +# /pair-capability-analyze-code-quality — Code Quality Analysis Evaluate code quality using objective metrics from [code-metrics.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/code-metrics.md). Produces a quality report with complexity, size, coverage, duplication, and maintainability scores. Includes actionable recommendations for improvement. **Output-only**: this skill inspects code and runs coverage but writes no files — it never mutates adoption, code, or the PM tool. @@ -141,7 +141,7 @@ RESULT: [Quality score: N/100 | Assessed | Confirmed existing] When composed by `/pair-process-review`: -- **Input**: /pair-process-review may invoke `/pair-capability-assess-code-quality` during the technical review phase. +- **Input**: /pair-process-review may invoke `/pair-capability-analyze-code-quality` during the technical review phase. - **Output**: Returns the quality report. /pair-process-review incorporates metrics and hotspots into review findings. - Poor maintainability or high complexity may inform review recommendations. - Metrics are informational — they do not HALT the review. diff --git a/.claude/skills/pair-capability-assess-debt/SKILL.md b/.claude/skills/pair-capability-analyze-debt/SKILL.md similarity index 97% rename from .claude/skills/pair-capability-assess-debt/SKILL.md rename to .claude/skills/pair-capability-analyze-debt/SKILL.md index e041832a..873d91f8 100644 --- a/.claude/skills/pair-capability-assess-debt/SKILL.md +++ b/.claude/skills/pair-capability-analyze-debt/SKILL.md @@ -1,11 +1,11 @@ --- -name: pair-capability-assess-debt -description: "Assesses technical debt using resolution cascade (Argument > Adoption > Assessment). Categorizes debt (code, design, test, documentation, infrastructure), applies prioritization formula (impact x effort), proposes remediation priority. Output-only: returns a report, writes no files, creates no backlog items, never blocks. Idempotent. Invocable independently or composed by /pair-process-review." +name: pair-capability-analyze-debt +description: "Analyzes technical debt using resolution cascade (Argument > Adoption > Assessment). Categorizes debt (code, design, test, documentation, infrastructure), applies prioritization formula (impact x effort), proposes remediation priority. Output-only: returns a report, writes no files, creates no backlog items, never blocks. Idempotent. Invocable independently or composed by /pair-process-review." version: 0.5.0 author: Foomakers --- -# /pair-capability-assess-debt — Technical Debt Assessment +# /pair-capability-analyze-debt — Technical Debt Analysis 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**. @@ -173,7 +173,7 @@ RESULT: [N items assessed, N high-priority — report only, nothing created/bloc When composed by `/pair-process-review`: -- **Input**: /pair-process-review invokes `/pair-capability-assess-debt` during the completeness phase (Phase 4). +- **Input**: /pair-process-review invokes `/pair-capability-analyze-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. - /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. diff --git a/.claude/skills/pair-next/SKILL.md b/.claude/skills/pair-next/SKILL.md index 801b4d97..4276d8c6 100644 --- a/.claude/skills/pair-next/SKILL.md +++ b/.claude/skills/pair-next/SKILL.md @@ -49,8 +49,8 @@ The catalog is **derived from the installed corpus**: every installed skill must | `/pair-capability-assess-pm` | Assessment | Assess project management tool | | `/pair-capability-assess-infrastructure`| Assessment| Assess infrastructure strategy | | `/pair-capability-assess-observability`| Assessment | Assess observability strategy | -| `/pair-capability-assess-debt` | Assessment | Assess technical debt with prioritization | -| `/pair-capability-assess-code-quality`| Assessment | Assess code quality with metrics | +| `/pair-capability-analyze-debt` | Analysis | Analyze technical debt with prioritization | +| `/pair-capability-analyze-code-quality`| Analysis | Analyze code quality with metrics | | `/pair-capability-estimate` | Planning | Estimate story using adopted methodology | | `/pair-capability-setup-gates` | Configuration| Configure CI/CD quality gates | | `/pair-capability-manage-flags` | Configuration| Manage feature flag lifecycle | @@ -117,7 +117,7 @@ If no process skill matched in Steps 2-3, check for capability skill opportuniti | --- | ------------------------------------------------------------------------ | -------------------- | ---------------------------------------------- | | 12 | Quality gate not configured (no Quality Gates section in way-of-working) | `/pair-capability-setup-gates` | Quality gates should be established | | 13 | Tech stack has unlisted dependencies detected | `/pair-capability-assess-stack` | Stack registry needs updating | -| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/pair-capability-assess-debt` | Debt should be cataloged and prioritized | +| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/pair-capability-analyze-debt` | Debt should be cataloged and prioritized | | 15 | No estimation methodology adopted in way-of-working | `/pair-capability-estimate` | Estimation process should be established | | 16 | A backlog item or topic carries open questions or unclear scope (question markers, conflicting comments) that block planning | `/pair-capability-grill` | Structured one-question-at-a-time alignment before planning | diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 074feb08..ee0f8bfd 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-review -description: "Reviews a pull request through a structured 6-phase process: validation, technical review, adoption compliance, completeness check, decision, and optional merge with parent cascade. Composes /pair-capability-verify-quality, /pair-capability-verify-done, /pair-capability-record-decision, /pair-capability-assess-debt (required) and /pair-capability-verify-adoption, /pair-capability-assess-stack (optional with graceful degradation). Output follows the code review template. Idempotent — re-invocation resumes from incomplete phases." +description: "Reviews a pull request through a structured 6-phase process: validation, technical review, adoption compliance, completeness check, decision, and optional merge with parent cascade. Composes /pair-capability-verify-quality, /pair-capability-verify-done, /pair-capability-record-decision, /pair-capability-analyze-debt (required) and /pair-capability-verify-adoption, /pair-capability-assess-stack (optional with graceful degradation). Output follows the code review template. Idempotent — re-invocation resumes from incomplete phases." version: 0.5.0 author: Foomakers --- @@ -16,7 +16,7 @@ Review a pull request through 6 sequential phases (5 review + 1 optional merge). | `/pair-capability-verify-quality` | Capability | Yes | 2 | Quality gate checking | | `/pair-capability-verify-done` | Capability | Yes | 4 | Definition of Done checking | | `/pair-capability-record-decision` | Capability | Yes | Any | Record missing ADR (HALT condition) | -| `/pair-capability-assess-debt` | Capability | Yes | 4 | Flag tech debt items | +| `/pair-capability-analyze-debt` | Capability | Yes | 4 | Flag tech debt items | | `/pair-capability-verify-adoption` | Capability | Optional | 3 | Full adoption compliance | | `/pair-capability-assess-stack` | Capability | Optional | 3 | Tech-stack resolution | | `/pair-capability-execute-manual-tests` | Capability | Optional | 6 | Post-merge release validation (manual tests) | @@ -191,9 +191,9 @@ This phase uses a **4-level graceful degradation cascade** depending on which op ### Step 4.2: Tech Debt Assessment -1. **Check**: Has `/pair-capability-assess-debt` already run in this session? +1. **Check**: Has `/pair-capability-analyze-debt` already run in this session? 2. **Skip**: If already run — reuse results, move to Phase 5. -3. **Act**: Compose `/pair-capability-assess-debt` with `$scope = all`. `/pair-capability-assess-debt` is **output-only** — it returns a report and creates nothing. +3. **Act**: Compose `/pair-capability-analyze-debt` with `$scope = all`. `/pair-capability-analyze-debt` is **output-only** — it returns a report and creates nothing. 4. **Act**: Report the debt items in the review output (Tech Debt section). Debt introduced by the PR is **surfaced, not blocked**: it does **not** HALT the review and **never** blocks the PR. Do **not** auto-create a tech-debt issue. 5. **Act**: If a debt item is worth scheduling, note it as a recommendation for **deliberate** promotion after review via `/pair-capability-write-issue` (with the `tech-debt` label) — a manual, selective act, never automatic. 6. **Verify**: Debt items recorded in the report. High-severity items may inform the review verdict (TECH-DEBT: approve + track separately) but never force CHANGES-REQUESTED on debt grounds alone. @@ -211,7 +211,7 @@ This phase uses a **4-level graceful degradation cascade** depending on which op - **Documentation Review**: documentation completeness (from /pair-capability-verify-done) - **Detailed Review Comments**: issues by severity, positive feedback - **Risk Assessment**: technical and business risks - - **Tech Debt**: items flagged by /pair-capability-assess-debt + - **Tech Debt**: items flagged by /pair-capability-analyze-debt - **Adoption Compliance**: results from Phase 3 (with degradation level noted) ### Step 5.2: Make Review Decision @@ -373,7 +373,7 @@ Re-invoking `/pair-process-review` on a partially reviewed PR is safe: - **/pair-capability-verify-adoption not installed**: Falls back to inline dependency checking against [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md). Warning logged. See degradation cascade (Phase 3). - **/pair-capability-assess-stack not installed**: Unlisted dependencies flagged as warnings for manual verification. Does NOT HALT. -- **/pair-capability-assess-debt not available**: Skip debt assessment, note in report. +- **/pair-capability-analyze-debt not available**: Skip debt assessment, note in report. - **Story not found**: Review proceeds with PR-only validation (no AC check). Phase 6 skips parent cascade. - **Code review template not found**: **HALT** — cannot produce review without template. - **PM tool not accessible**: Ask reviewer to manually provide PR details. Phase 6 merge via CLI only. diff --git a/.pair/adoption/decision-log/2026-07-13-skill-naming-verb-taxonomy.md b/.pair/adoption/decision-log/2026-07-13-skill-naming-verb-taxonomy.md new file mode 100644 index 00000000..39df4e78 --- /dev/null +++ b/.pair/adoption/decision-log/2026-07-13-skill-naming-verb-taxonomy.md @@ -0,0 +1,56 @@ +# Decision: Skill naming verb taxonomy — verify / assess / analyze (analyze-* for report skills) + +## Date + +2026-07-13 + +## Status + +Active + +## Category + +Convention Adoption + +## Context + +The capability-skill corpus uses a verb prefix to signal what a skill *does*. Two verbs were clear, one was overloaded: + +- `verify-*` (verify-quality, verify-done, verify-adoption) — a **conformance** check that yields pass/fail against a standard. +- `assess-*` — used for **two different operations** at once: (a) the 8 "decision" skills (assess-stack, assess-architecture, assess-methodology, assess-pm, assess-testing, assess-infrastructure, assess-observability, assess-ai) that evaluate options and **propose an adoption choice** (output-only proposal persisted by `/record-decision` per ADR-009); and (b) 2 "report" skills (assess-debt, assess-code-quality) that **only analyze and report** — they propose no adoption decision and never block a PR. + +Folding "propose a decision" and "report only" under one verb blurred the reader's and the LLM router's expectation of a skill's effect, and made the `assess-*` descriptions harder to differentiate (a known #313 finding). The two report skills are conceptually neither conformance gates (`verify-*`) nor decision proposers (`assess-*`). + +## Decision + +Adopt a **three-verb taxonomy** for capability skills, one verb per operation, not overloaded across branches: + +- **`verify-*`** = conformance pass/fail against a standard. (verify-quality, verify-done, verify-adoption) — unchanged. +- **`assess-*`** = evaluate options and **PROPOSE** an adoption choice; output-only proposal, persisted by `/record-decision` (ADR-009). The 8 decision skills — unchanged. +- **`analyze-*`** = analyze and **REPORT** only; proposes no adoption decision, creates nothing, never blocks a PR. + +Rename the 2 report skills to the `analyze-*` verb: + +- `assess-debt` → **`analyze-debt`** +- `assess-code-quality` → **`analyze-code-quality`** + +Applies to both the dataset (`packages/knowledge-hub/dataset/.skills/capability/`) and the installed mirror (`.claude/skills/pair-capability-*`), renamed with `git mv` to preserve history. This is a **rename only** — no behavior change; both skills remain output-only report producers (ADR-009 still governs their output-only contract). The corpus stays at 35 skills. + +## Alternatives Considered + +- **Keep `assess-*` for all 10**: Rejected. Overloads one verb across "propose a decision" vs "report only", which is the ambiguity #313 set out to remove; leaves the 2 report skills mis-signaling that they might write/decide. +- **Fold the 2 report skills under `verify-*`**: Rejected. They produce a graded report (metrics, prioritized items), not a pass/fail conformance verdict; `verify-*` implies a gate, which debt/quality analysis explicitly is not (debt never blocks a PR, R7.2). +- **A `report-*` verb instead of `analyze-*`**: Rejected. "analyze" names the *operation* (the skills analyze code/debt and emit a report); "report" names only the artifact. `analyze-*` reads as the active capability and pairs cleanly against `verify-*`/`assess-*`. + +## Consequences + +- **Clear reader/router expectation**: the verb alone tells you whether a skill gates (verify), proposes a decision (assess), or only reports (analyze). +- **Sharper descriptions/eval**: the report skills no longer sit inside the `assess-*` near-clone cluster, aiding trigger differentiation (#313 T3/T7). +- **Migration cost**: every cross-reference to the old names had to move in lockstep — router catalog + cascade, `/review` composition contract, skills-guide categories + Migration Notes, skills-catalog rows, writing-skills naming table, eval trigger-prompts, and the #224 conformance test. All done in the same PR (#313/T8). +- **History preserved, not rewritten**: point-in-time records that predate the rename (ADR-009, the 2026-07-12 eval baseline) keep the old names as historical fact; the forward mapping lives in the skills-guide Migration Notes and this ADL. + +## Adoption Impact + +- Renamed skill dirs (dataset + mirror): `capability/analyze-debt/`, `capability/analyze-code-quality/`; `.claude/skills/pair-capability-analyze-debt/`, `.claude/skills/pair-capability-analyze-code-quality/`. +- Cross-references updated: `next` router (catalog rows + cascade row 14, category "Analysis"); `process/review` (required composed skill `/analyze-debt`); `skills-guide.md` (new "Analysis Skills" group; Verification = only the 3 `verify-*`; `manage-flags` → Operational; Code Quality bucket dissolved; Migration Notes entry); `apps/website/content/docs/reference/skills-catalog.mdx` (new "Analysis Capabilities" section); `apps/website/content/docs/concepts/skills.mdx`; `apps/website/content/docs/contributing/writing-skills.mdx` (verb taxonomy row + rule); `packages/knowledge-hub/eval/trigger-prompts.json` (family `analyze-report`); `packages/knowledge-hub/src/conformance/assess-output-only.test.ts` (analyze-* output-only + analyze-debt no scan-mode). +- Complements (does not amend) [adr-009-assess-output-only](../tech/adr/adr-009-assess-output-only.md): that decision makes assess-*/analyze-* output-only and names `/record-decision` the sole adoption writer; this ADL only renames the 2 report skills' verb. No dataset mirror of this ADL — sibling ADLs in `adoption/decision-log/` are adoption-only records. diff --git a/.pair/knowledge/skills-guide.md b/.pair/knowledge/skills-guide.md index a65a58fe..50bd0557 100644 --- a/.pair/knowledge/skills-guide.md +++ b/.pair/knowledge/skills-guide.md @@ -37,7 +37,7 @@ Process skills compose capability skills. Capability skills are independently in > How-to guides 04 and 05 (subdomain/bounded-context definition) no longer map to a process skill — see [Domain Modeling Skills](#domain-modeling-skills-2) below and [Migration Notes](#migration-notes). -### Capability Skills (24) +### Capability Skills (25) #### Domain Modeling Skills (2) @@ -61,16 +61,24 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/pair-capability-assess-observability` | Observability strategy evaluation | | `/pair-capability-assess-ai` | AI development tools evaluation | -#### Verification Skills (4) +#### Analysis Skills (2) + +Analyze + **report only** — never block, propose no adoption decision (verb: `analyze-*`, distinct from `assess-*`). + +| Skill | Scope | +|-------|-------| +| `/pair-capability-analyze-debt` | Technical debt detection + prioritization (report-only) | +| `/pair-capability-analyze-code-quality` | Code quality metrics — complexity, size, coverage, maintainability (report-only) | + +#### Verification Skills (3) | Skill | Scope | |-------|-------| | `/pair-capability-verify-quality` | Quality gate checking | | `/pair-capability-verify-done` | Definition of Done checking | | `/pair-capability-verify-adoption` | Adoption compliance checking | -| `/pair-capability-assess-debt` | Technical debt detection + prioritization | -#### Operational Skills (5) +#### Operational Skills (6) | Skill | Scope | |-------|-------| @@ -79,6 +87,7 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/pair-capability-estimate` | Story estimation | | `/pair-capability-setup-gates` | CI/CD quality gate configuration | | `/pair-capability-setup-pm` | PM tool configuration | +| `/pair-capability-manage-flags` | Feature flag lifecycle management | #### Testing Skills (2) @@ -87,12 +96,11 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/pair-capability-design-manual-tests` | Manual test suite generation from project analysis | | `/pair-capability-execute-manual-tests` | Manual test suite execution + report generation | -#### Code Quality Skills (2) +#### State and Handoff Skills (1) | Skill | Scope | |-------|-------| -| `/pair-capability-assess-code-quality` | Code quality metrics assessment | -| `/pair-capability-manage-flags` | Feature flag lifecycle management | +| `/pair-capability-checkpoint` | Write/resume story progress checkpoint (work survives context resets) | #### Discovery Skills (1) @@ -126,7 +134,9 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- │ ├── estimate/ │ ├── setup-gates/ │ ├── setup-pm/ -│ ├── assess-code-quality/ +│ ├── analyze-debt/ # report-only +│ ├── analyze-code-quality/ # report-only +│ ├── checkpoint/ │ ├── manage-flags/ │ └── grill/ └── next/ # Navigator skill @@ -191,6 +201,13 @@ No caller performs a full re-mapping outside `/pair-process-bootstrap`. When no - New behavior: graceful "system areas" fallback when no DDD artifacts exist; `Volatility` field on subdomains; per-relationship strength/distance/volatility assessment with an approval gate on unbalanced+volatile relationships (see `subdomain-template.md`, `bounded-context-template.md`). - No standalone process step remains for domain mapping — how-to guides 04/05 still describe the workflow, but the underlying skill is invoked scoped by the callers in the [Callers Matrix](#callers-matrix-scoped-capabilities) above. +**assess-debt, assess-code-quality: assess → analyze (skill naming taxonomy, #313/T8)** + +- Rationale: `assess-*` conflated two operations. The corpus now uses three distinct verbs — **`verify-*`** (conformance pass/fail), **`assess-*`** (evaluate options + PROPOSE an adoption choice — the 8 decision skills), **`analyze-*`** (analyze + REPORT only, never blocks, proposes no adoption decision). The two report skills were misfiled under `assess-*` and are renamed to the `analyze-*` verb. Recorded as ADL `2026-07-13-skill-naming-verb-taxonomy.md` in the project decision log. +- Old path: `.skills/capability/assess-debt/`, `.skills/capability/assess-code-quality/` — new path: `.skills/capability/analyze-debt/`, `.skills/capability/analyze-code-quality/`. +- Installed command names change accordingly: `/pair-capability-assess-debt` → `/pair-capability-analyze-debt`; `/pair-capability-assess-code-quality` → `/pair-capability-analyze-code-quality`. Unprefixed dataset command names change too: `/assess-debt` → `/analyze-debt`, `/assess-code-quality` → `/analyze-code-quality`. +- No behavior change: both remain output-only report producers (per ADR-009); only the verb/name changed. Skill count stays 35. + ## How Skills Relate to How-To Guides - **How-to guides** = workflow orchestrators (the "what" and "when") @@ -215,4 +232,4 @@ Skills read from and write to adoption files in `.pair/adoption/`: - **Start here**: Run `/pair-next` to determine what to do - **Process flow**: `/pair-process-specify-prd` → `/pair-process-bootstrap` → `/pair-process-plan-initiatives` → ... → `/pair-process-implement` → `/pair-process-review` -- **Independent capability**: Any capability skill can be invoked directly (e.g., `/pair-capability-estimate`, `/pair-capability-assess-debt`) +- **Independent capability**: Any capability skill can be invoked directly (e.g., `/pair-capability-estimate`, `/pair-capability-analyze-debt`) diff --git a/apps/website/content/docs/concepts/skills.mdx b/apps/website/content/docs/concepts/skills.mdx index 5925cc89..6ed44f67 100644 --- a/apps/website/content/docs/concepts/skills.mdx +++ b/apps/website/content/docs/concepts/skills.mdx @@ -65,7 +65,7 @@ And `/review` composes: - `/verify-quality` — to check quality gates on the PR - `/verify-done` — to check Definition of Done criteria -- `/assess-debt` — to evaluate technical debt +- `/analyze-debt` — to analyze and report technical debt - `/record-decision` — if a decision needs recording This composition means complex processes are built from simple, tested parts. Each capability skill works the same whether invoked directly or composed by a process skill. diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 6c1a258b..359e3bcc 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -267,7 +267,11 @@ Add your skill to `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.m |-----------|---------| | Process skills | `pair-process-` (e.g., `pair-process-implement`) | | Capability skills | `pair-capability-` (e.g., `pair-capability-verify-quality`) | -| Assessment skills | `pair-capability-assess-` (e.g., `pair-capability-assess-stack`) | +| Verification skills | `pair-capability-verify-` — conformance pass/fail (e.g., `pair-capability-verify-quality`) | +| Assessment skills | `pair-capability-assess-` — evaluate options + propose an adoption choice (e.g., `pair-capability-assess-stack`) | +| Analysis skills | `pair-capability-analyze-` — analyze + report only, never blocks (e.g., `pair-capability-analyze-debt`) | + +Three distinct verbs, kept separate — don't overload one across branches: **`verify-*`** = conformance pass/fail; **`assess-*`** = evaluate options and PROPOSE an adoption decision; **`analyze-*`** = analyze and REPORT only (no decision, never blocks). Recorded as ADL `2026-07-13-skill-naming-verb-taxonomy.md`. ## Resources diff --git a/apps/website/content/docs/reference/skills-catalog.mdx b/apps/website/content/docs/reference/skills-catalog.mdx index 0bec8000..2b5253a1 100644 --- a/apps/website/content/docs/reference/skills-catalog.mdx +++ b/apps/website/content/docs/reference/skills-catalog.mdx @@ -5,7 +5,7 @@ description: Complete catalog of all 35 pair skills organized by type — proces pair ships with 35 skills organized into three types: **process** (workflow orchestration), **capability** (atomic operations), and **meta** (navigation). Each skill is a `SKILL.md` file invoked as a slash command by your AI coding assistant. -> **Last updated:** 2026-07-11. Source: `packages/knowledge-hub/dataset/.skills/` +> **Last updated:** 2026-07-13. Source: `packages/knowledge-hub/dataset/.skills/` ## Meta Skills @@ -27,7 +27,7 @@ Process skills orchestrate multi-step workflows by composing capability skills. | **refine-story** | `/pair-process-refine-story` | Refines a user story from Todo to Refined state: requirements analysis (Given-When-Then), technical analysis, sprint readiness. | `/pair-capability-write-issue` | | **plan-tasks** | `/pair-process-plan-tasks` | Breaks a refined user story into implementation tasks. Appends Technical Analysis + Task Breakdown to the story body. | `/pair-capability-write-issue` | | **implement** | `/pair-process-implement` | Implements a user story by iterating through its tasks one at a time following a 5-step cycle per task. Creates a PR at story completion. | `/pair-capability-verify-quality`, `/pair-capability-record-decision` | -| **review** | `/pair-process-review` | Reviews a pull request through a structured 6-phase process: validation, technical review, adoption compliance, completeness, decision, and optional merge. | `/pair-capability-verify-quality`, `/pair-capability-verify-done`, `/pair-capability-record-decision`, `/pair-capability-assess-debt` (required); `/pair-capability-verify-adoption`, `/pair-capability-assess-stack`, `/pair-capability-execute-manual-tests` (optional) | +| **review** | `/pair-process-review` | Reviews a pull request through a structured 6-phase process: validation, technical review, adoption compliance, completeness, decision, and optional merge. | `/pair-capability-verify-quality`, `/pair-capability-verify-done`, `/pair-capability-record-decision`, `/pair-capability-analyze-debt` (required); `/pair-capability-verify-adoption`, `/pair-capability-assess-stack`, `/pair-capability-execute-manual-tests` (optional) | ## Capability Skills @@ -50,8 +50,6 @@ All `assess-*` skills are **output-only**: they produce a proposal (rendered ado | ----- | ------- | ----------- | | **assess-ai** | `/pair-capability-assess-ai` | Assess AI development tools using resolution cascade (Argument > Adoption > Assessment). Output-only — proposes AI-section content; caller persists via `/pair-capability-record-decision`. | | **assess-architecture** | `/pair-capability-assess-architecture` | Assess architecture pattern using resolution cascade. Output-only — proposes adoption content; caller persists via `/pair-capability-record-decision`. | -| **assess-code-quality** | `/pair-capability-assess-code-quality` | Assess code quality using quality score formula from code-metrics guidelines. Output-only — report; writes nothing. | -| **assess-debt** | `/pair-capability-assess-debt` | Assess technical debt (code, design, test, documentation, infrastructure) with impact×effort prioritization. Output-only — report; no scan-mode, no auto-created issues, never blocks a PR. | | **assess-infrastructure** | `/pair-capability-assess-infrastructure` | Assess infrastructure strategy: cloud, CI/CD, deployment choices. Output-only — proposes adoption content; caller persists via `/pair-capability-record-decision`. | | **assess-methodology** | `/pair-capability-assess-methodology` | Assess development methodology: Scrum, Kanban, Lean, etc. Output-only — proposes methodology-section content; caller persists via `/pair-capability-record-decision`. | | **assess-observability** | `/pair-capability-assess-observability` | Assess observability strategy: monitoring, logging, tracing. Output-only — proposes observability-section content; caller persists via `/pair-capability-record-decision`. | @@ -59,6 +57,15 @@ All `assess-*` skills are **output-only**: they produce a proposal (rendered ado | **assess-stack** | `/pair-capability-assess-stack` | Assess tech stack with version tracking. Lifecycle-spanning: bootstrap (full eval), implementation (add dependency), review (detect unlisted). Output-only — proposes tech-stack content; caller persists via `/pair-capability-record-decision`. | | **assess-testing** | `/pair-capability-assess-testing` | Assess testing framework and strategy. Output-only — proposes testing-section content; caller persists via `/pair-capability-record-decision`. | +### Analysis Capabilities + +All `analyze-*` skills are **output-only report producers**: they analyze and report, propose no adoption decision, and never block a PR. Distinct from `assess-*` (evaluate options + propose an adoption choice) and `verify-*` (conformance pass/fail). See ADL `2026-07-13-skill-naming-verb-taxonomy.md` in the project decision log. + +| Skill | Command | Description | +| ----- | ------- | ----------- | +| **analyze-code-quality** | `/pair-capability-analyze-code-quality` | Analyze code quality using quality score formula from code-metrics guidelines. Output-only — report; writes nothing. | +| **analyze-debt** | `/pair-capability-analyze-debt` | Analyze technical debt (code, design, test, documentation, infrastructure) with impact×effort prioritization. Output-only — report; no scan-mode, no auto-created issues, never blocks a PR. | + ### Verification Capabilities | Skill | Command | Description | diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md index 991568fb..f1b2eb2b 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md @@ -37,7 +37,7 @@ Process skills compose capability skills. Capability skills are independently in > How-to guides 04 and 05 (subdomain/bounded-context definition) were removed — domain modeling is referenced inline by each real caller's own how-to (02, 03, 06, 09; 08 planned — #242). See [Domain Modeling Skills](#domain-modeling-skills-2) below and [Migration Notes](#migration-notes). -### Capability Skills (24) +### Capability Skills (25) #### Domain Modeling Skills (2) @@ -61,16 +61,24 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/assess-observability` | Observability strategy evaluation | | `/assess-ai` | AI development tools evaluation | -#### Verification Skills (4) +#### Analysis Skills (2) + +Analyze + **report only** — never block, propose no adoption decision (verb: `analyze-*`, distinct from `assess-*`). + +| Skill | Scope | +|-------|-------| +| `/analyze-debt` | Technical debt detection + prioritization (report-only) | +| `/analyze-code-quality` | Code quality metrics — complexity, size, coverage, maintainability (report-only) | + +#### Verification Skills (3) | Skill | Scope | |-------|-------| | `/verify-quality` | Quality gate checking | | `/verify-done` | Definition of Done checking | | `/verify-adoption` | Adoption compliance checking | -| `/assess-debt` | Technical debt detection + prioritization | -#### Operational Skills (5) +#### Operational Skills (6) | Skill | Scope | |-------|-------| @@ -79,6 +87,7 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/estimate` | Story estimation | | `/setup-gates` | CI/CD quality gate configuration | | `/setup-pm` | PM tool configuration | +| `/manage-flags` | Feature flag lifecycle management | #### Testing Skills (2) @@ -87,12 +96,11 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/design-manual-tests` | Manual test suite generation from project analysis | | `/execute-manual-tests` | Manual test suite execution + report generation | -#### Code Quality Skills (2) +#### State and Handoff Skills (1) | Skill | Scope | |-------|-------| -| `/assess-code-quality` | Code quality metrics assessment | -| `/manage-flags` | Feature flag lifecycle management | +| `/checkpoint` | Write/resume story progress checkpoint (work survives context resets) | #### Discovery Skills (1) @@ -126,7 +134,9 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- │ ├── estimate/ │ ├── setup-gates/ │ ├── setup-pm/ -│ ├── assess-code-quality/ +│ ├── analyze-debt/ # report-only +│ ├── analyze-code-quality/ # report-only +│ ├── checkpoint/ │ ├── manage-flags/ │ └── grill/ └── next/ # Navigator skill @@ -191,6 +201,13 @@ Every row above except the two `(planned — #242)`/`(planned — #230)` entries - New behavior: graceful "system areas" fallback when no DDD artifacts exist; `Volatility` field on subdomains; per-relationship strength/distance/volatility assessment with an approval gate on unbalanced+volatile relationships (see `subdomain-template.md`, `bounded-context-template.md`). - No standalone process step or how-to remains for domain mapping — how-to guides 04 (define-subdomains) and 05 (define-bounded-contexts) were removed; each caller's own how-to (02, 03, 06, 08, 09) now references the capability inline at the point it's invoked, scoped per the [Callers Matrix](#callers-matrix-scoped-capabilities) above. The capability's own `SKILL.md` ([map-subdomains](../../.skills/capability/map-subdomains/SKILL.md), [map-contexts](../../.skills/capability/map-contexts/SKILL.md)) is the canonical reference for its algorithm, fallback behavior, and templates. +**assess-debt, assess-code-quality: assess → analyze (skill naming taxonomy, #313/T8)** + +- Rationale: `assess-*` conflated two operations. The corpus now uses three distinct verbs — **`verify-*`** (conformance pass/fail), **`assess-*`** (evaluate options + PROPOSE an adoption choice — the 8 decision skills), **`analyze-*`** (analyze + REPORT only, never blocks, proposes no adoption decision). The two report skills were misfiled under `assess-*` and are renamed to the `analyze-*` verb. Recorded as ADL `2026-07-13-skill-naming-verb-taxonomy.md` in the project decision log. +- Old path: `.skills/capability/assess-debt/`, `.skills/capability/assess-code-quality/` — new path: `.skills/capability/analyze-debt/`, `.skills/capability/analyze-code-quality/`. +- Installed command names change accordingly: `/pair-capability-assess-debt` → `/pair-capability-analyze-debt`; `/pair-capability-assess-code-quality` → `/pair-capability-analyze-code-quality`. Unprefixed dataset command names change too: `/assess-debt` → `/analyze-debt`, `/assess-code-quality` → `/analyze-code-quality`. +- No behavior change: both remain output-only report producers (per ADR-009); only the verb/name changed. Skill count stays 35. + ## How Skills Relate to How-To Guides - **How-to guides** = workflow orchestrators (the "what" and "when") @@ -215,4 +232,4 @@ Skills read from and write to adoption files in `.pair/adoption/`: - **Start here**: Run `/next` to determine what to do - **Process flow**: `/specify-prd` → `/bootstrap` → `/plan-initiatives` → ... → `/implement` → `/review` -- **Independent capability**: Any capability skill can be invoked directly (e.g., `/estimate`, `/assess-debt`) +- **Independent capability**: Any capability skill can be invoked directly (e.g., `/estimate`, `/analyze-debt`) diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-code-quality/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/analyze-code-quality/SKILL.md similarity index 97% rename from packages/knowledge-hub/dataset/.skills/capability/assess-code-quality/SKILL.md rename to packages/knowledge-hub/dataset/.skills/capability/analyze-code-quality/SKILL.md index 256550ae..23af276b 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-code-quality/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/analyze-code-quality/SKILL.md @@ -1,11 +1,11 @@ --- -name: assess-code-quality -description: "Assesses code quality using resolution cascade (Argument > Adoption > Assessment). Applies quality score formula from code-metrics guidelines. Produces quality report with complexity, size, coverage, and maintainability metrics (output-only, writes nothing). Idempotent: detects existing report, checks staleness. Invocable independently or composed by /review." +name: analyze-code-quality +description: "Analyzes code quality using resolution cascade (Argument > Adoption > Assessment). Applies quality score formula from code-metrics guidelines. Produces quality report with complexity, size, coverage, and maintainability metrics (output-only, writes nothing). Idempotent: detects existing report, checks staleness. Invocable independently or composed by /review." version: 0.5.0 author: Foomakers --- -# /assess-code-quality — Code Quality Assessment +# /analyze-code-quality — Code Quality Analysis Evaluate code quality using objective metrics from [code-metrics.md](../../../.pair/knowledge/guidelines/code-design/quality-standards/code-metrics.md). Produces a quality report with complexity, size, coverage, duplication, and maintainability scores. Includes actionable recommendations for improvement. **Output-only**: this skill inspects code and runs coverage but writes no files — it never mutates adoption, code, or the PM tool. @@ -141,7 +141,7 @@ RESULT: [Quality score: N/100 | Assessed | Confirmed existing] When composed by `/review`: -- **Input**: /review may invoke `/assess-code-quality` during the technical review phase. +- **Input**: /review may invoke `/analyze-code-quality` during the technical review phase. - **Output**: Returns the quality report. /review incorporates metrics and hotspots into review findings. - Poor maintainability or high complexity may inform review recommendations. - Metrics are informational — they do not HALT the review. diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md similarity index 97% rename from packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md rename to packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md index 1b7eef3c..ae51f8b5 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-debt/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md @@ -1,11 +1,11 @@ --- -name: assess-debt -description: "Assesses technical debt using resolution cascade (Argument > Adoption > Assessment). Categorizes debt (code, design, test, documentation, infrastructure), applies prioritization formula (impact x effort), proposes remediation priority. Output-only: returns a report, writes no files, creates no backlog items, never blocks. Idempotent. Invocable independently or composed by /review." +name: analyze-debt +description: "Analyzes technical debt using resolution cascade (Argument > Adoption > Assessment). Categorizes debt (code, design, test, documentation, infrastructure), applies prioritization formula (impact x effort), proposes remediation priority. Output-only: returns a report, writes no files, creates no backlog items, never blocks. Idempotent. Invocable independently or composed by /review." version: 0.5.0 author: Foomakers --- -# /assess-debt — Technical Debt Assessment +# /analyze-debt — Technical Debt Analysis 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**. @@ -173,7 +173,7 @@ RESULT: [N items assessed, N high-priority — report only, nothing created/bloc When composed by `/review`: -- **Input**: /review invokes `/assess-debt` during the completeness phase (Phase 4). +- **Input**: /review invokes `/analyze-debt` during the completeness phase (Phase 4). - **Output**: Returns the debt assessment report. /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. - /review does **not** auto-create tech-debt issues. Items worth tracking are promoted deliberately (after review) via `/write-issue` with the `tech-debt` label. diff --git a/packages/knowledge-hub/dataset/.skills/next/SKILL.md b/packages/knowledge-hub/dataset/.skills/next/SKILL.md index f07571e5..e7205f50 100644 --- a/packages/knowledge-hub/dataset/.skills/next/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/next/SKILL.md @@ -49,8 +49,8 @@ The catalog is **derived from the installed corpus**: every skill directory unde | `/assess-pm` | Assessment | Assess project management tool | | `/assess-infrastructure`| Assessment| Assess infrastructure strategy | | `/assess-observability`| Assessment | Assess observability strategy | -| `/assess-debt` | Assessment | Assess technical debt with prioritization | -| `/assess-code-quality`| Assessment | Assess code quality with metrics | +| `/analyze-debt` | Analysis | Analyze technical debt with prioritization | +| `/analyze-code-quality`| Analysis | Analyze code quality with metrics | | `/estimate` | Planning | Estimate story using adopted methodology | | `/setup-gates` | Configuration| Configure CI/CD quality gates | | `/manage-flags` | Configuration| Manage feature flag lifecycle | @@ -117,7 +117,7 @@ If no process skill matched in Steps 2-3, check for capability skill opportuniti | --- | ------------------------------------------------------------------------ | -------------------- | ---------------------------------------------- | | 12 | Quality gate not configured (no Quality Gates section in way-of-working) | `/setup-gates` | Quality gates should be established | | 13 | Tech stack has unlisted dependencies detected | `/assess-stack` | Stack registry needs updating | -| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/assess-debt` | Debt should be cataloged and prioritized | +| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/analyze-debt` | Debt should be cataloged and prioritized | | 15 | No estimation methodology adopted in way-of-working | `/estimate` | Estimation process should be established | | 16 | A backlog item or topic carries open questions or unclear scope (question markers, conflicting comments) that block planning | `/grill` | Structured one-question-at-a-time alignment before planning | diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index 9a9bf1bc..f63b2e83 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -1,6 +1,6 @@ --- name: review -description: "Reviews a pull request through a structured 6-phase process: validation, technical review, adoption compliance, completeness check, decision, and optional merge with parent cascade. Composes /verify-quality, /verify-done, /record-decision, /assess-debt (required) and /verify-adoption, /assess-stack (optional with graceful degradation). Output follows the code review template. Idempotent — re-invocation resumes from incomplete phases." +description: "Reviews a pull request through a structured 6-phase process: validation, technical review, adoption compliance, completeness check, decision, and optional merge with parent cascade. Composes /verify-quality, /verify-done, /record-decision, /analyze-debt (required) and /verify-adoption, /assess-stack (optional with graceful degradation). Output follows the code review template. Idempotent — re-invocation resumes from incomplete phases." version: 0.5.0 author: Foomakers --- @@ -16,7 +16,7 @@ Review a pull request through 6 sequential phases (5 review + 1 optional merge). | `/verify-quality` | Capability | Yes | 2 | Quality gate checking | | `/verify-done` | Capability | Yes | 4 | Definition of Done checking | | `/record-decision` | Capability | Yes | Any | Record missing ADR (HALT condition) | -| `/assess-debt` | Capability | Yes | 4 | Flag tech debt items | +| `/analyze-debt` | Capability | Yes | 4 | Flag tech debt items | | `/verify-adoption` | Capability | Optional | 3 | Full adoption compliance | | `/assess-stack` | Capability | Optional | 3 | Tech-stack resolution | | `/execute-manual-tests` | Capability | Optional | 6 | Post-merge release validation (manual tests) | @@ -191,9 +191,9 @@ This phase uses a **4-level graceful degradation cascade** depending on which op ### Step 4.2: Tech Debt Assessment -1. **Check**: Has `/assess-debt` already run in this session? +1. **Check**: Has `/analyze-debt` already run in this session? 2. **Skip**: If already run — reuse results, move to Phase 5. -3. **Act**: Compose `/assess-debt` with `$scope = all`. `/assess-debt` is **output-only** — it returns a report and creates nothing. +3. **Act**: Compose `/analyze-debt` with `$scope = all`. `/analyze-debt` is **output-only** — it returns a report and creates nothing. 4. **Act**: Report the debt items in the review output (Tech Debt section). Debt introduced by the PR is **surfaced, not blocked**: it does **not** HALT the review and **never** blocks the PR. Do **not** auto-create a tech-debt issue. 5. **Act**: If a debt item is worth scheduling, note it as a recommendation for **deliberate** promotion after review via `/write-issue` (with the `tech-debt` label) — a manual, selective act, never automatic. 6. **Verify**: Debt items recorded in the report. High-severity items may inform the review verdict (TECH-DEBT: approve + track separately) but never force CHANGES-REQUESTED on debt grounds alone. @@ -211,7 +211,7 @@ This phase uses a **4-level graceful degradation cascade** depending on which op - **Documentation Review**: documentation completeness (from /verify-done) - **Detailed Review Comments**: issues by severity, positive feedback - **Risk Assessment**: technical and business risks - - **Tech Debt**: items flagged by /assess-debt + - **Tech Debt**: items flagged by /analyze-debt - **Adoption Compliance**: results from Phase 3 (with degradation level noted) ### Step 5.2: Make Review Decision @@ -373,7 +373,7 @@ Re-invoking `/review` on a partially reviewed PR is safe: - **/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. -- **/assess-debt not available**: Skip debt assessment, note in report. +- **/analyze-debt not available**: Skip debt assessment, note in report. - **Story not found**: Review proceeds with PR-only validation (no AC check). Phase 6 skips parent cascade. - **Code review template not found**: **HALT** — cannot produce review without template. - **PM tool not accessible**: Ask reviewer to manually provide PR details. Phase 6 merge via CLI only. diff --git a/packages/knowledge-hub/eval/trigger-prompts.json b/packages/knowledge-hub/eval/trigger-prompts.json index 43f08919..488c4767 100644 --- a/packages/knowledge-hub/eval/trigger-prompts.json +++ b/packages/knowledge-hub/eval/trigger-prompts.json @@ -167,44 +167,44 @@ ] }, { - "family": "assess-report", - "skills": ["assess-code-quality", "assess-debt"], + "family": "analyze-report", + "skills": ["analyze-code-quality", "analyze-debt"], "prompts": [ { "id": "AR-01", "type": "should-trigger", - "expected": "assess-code-quality", + "expected": "analyze-code-quality", "prompt": "Give me a code quality report for this repo — complexity, size, coverage, the works." }, { "id": "AR-02", "type": "should-trigger", - "expected": "assess-code-quality", + "expected": "analyze-code-quality", "prompt": "How maintainable is this codebase right now? Score it." }, { "id": "AR-03", "type": "should-trigger", - "expected": "assess-debt", + "expected": "analyze-debt", "prompt": "Catalog our technical debt and tell us what to fix first." }, { "id": "AR-04", "type": "should-trigger", - "expected": "assess-debt", + "expected": "analyze-debt", "prompt": "The code is full of TODO and FIXME comments — prioritize the cleanup for us." }, { "id": "AR-N1", "type": "should-not-trigger", - "near_miss_for": "assess-code-quality", + "near_miss_for": "analyze-code-quality", "expected": "verify-quality", "prompt": "Is the quality gate passing? Run lint, tests and type-check and tell me." }, { "id": "AR-N2", "type": "should-not-trigger", - "near_miss_for": "assess-debt", + "near_miss_for": "analyze-debt", "expected": "none", "prompt": "Refactor the auth module to pay down its debt." } diff --git a/packages/knowledge-hub/src/conformance/assess-output-only.test.ts b/packages/knowledge-hub/src/conformance/assess-output-only.test.ts index bcbab685..5fe1f284 100644 --- a/packages/knowledge-hub/src/conformance/assess-output-only.test.ts +++ b/packages/knowledge-hub/src/conformance/assess-output-only.test.ts @@ -3,17 +3,20 @@ import { readFileSync, existsSync } from 'fs' import { join } from 'path' // Conformance guard for story #224: assess-* skills are output-only; -// record-decision is the sole adoption writer; assess-debt has no scan-mode. -// See adr-009-assess-output-only.md. +// record-decision is the sole adoption writer. The two report skills were renamed +// assess-debt → analyze-debt and assess-code-quality → analyze-code-quality +// (#313/T8 — skill naming verb taxonomy: verify/assess/analyze). They remain +// output-only and analyze-debt still has no scan-mode. +// See adr-009-assess-output-only.md and the taxonomy ADL +// (decision-log/2026-07-13-skill-naming-verb-taxonomy.md). const DATASET = join(__dirname, '../../dataset/.skills/capability') const MIRROR = join(__dirname, '../../../../.claude/skills') +// The 8 "decision" assess-* skills: evaluate options + propose an adoption choice. const ASSESS_SKILLS = [ 'ai', 'architecture', - 'code-quality', - 'debt', 'infrastructure', 'methodology', 'observability', @@ -22,18 +25,21 @@ const ASSESS_SKILLS = [ 'testing', ] -function dataset(skill: string): string { - return readFileSync(join(DATASET, `assess-${skill}`, 'SKILL.md'), 'utf-8') +// The 2 "report" analyze-* skills: analyze + report only, never block, no decision. +const ANALYZE_SKILLS = ['code-quality', 'debt'] + +function dataset(dir: string): string { + return readFileSync(join(DATASET, dir, 'SKILL.md'), 'utf-8') } -function mirror(skill: string): string { - return readFileSync(join(MIRROR, `pair-capability-assess-${skill}`, 'SKILL.md'), 'utf-8') +function mirror(dir: string): string { + return readFileSync(join(MIRROR, dir, 'SKILL.md'), 'utf-8') } describe('assess-* skills are output-only (#224)', () => { for (const skill of ASSESS_SKILLS) { it(`assess-${skill} declares output-only and has no adoption-write step`, () => { - const content = dataset(skill) + const content = dataset(`assess-${skill}`) // Contract is stated explicitly. expect(content.toLowerCase()).toContain('output-only') // The old "Write Adoption File" step must be gone (renamed to a render/proposal step). @@ -43,20 +49,36 @@ describe('assess-* skills are output-only (#224)', () => { it(`assess-${skill} has an installed mirror that is also output-only`, () => { const mirrorPath = join(MIRROR, `pair-capability-assess-${skill}`, 'SKILL.md') expect(existsSync(mirrorPath)).toBe(true) - expect(mirror(skill).toLowerCase()).toContain('output-only') + expect(mirror(`pair-capability-assess-${skill}`).toLowerCase()).toContain('output-only') + }) + } +}) + +describe('analyze-* report skills are output-only (#224; renamed #313/T8)', () => { + for (const skill of ANALYZE_SKILLS) { + it(`analyze-${skill} declares output-only and has no adoption-write step`, () => { + const content = dataset(`analyze-${skill}`) + expect(content.toLowerCase()).toContain('output-only') + expect(content).not.toMatch(/#+\s*Step\s*\d+:\s*Write Adoption File/i) + }) + + it(`analyze-${skill} has an installed mirror that is also output-only`, () => { + const mirrorPath = join(MIRROR, `pair-capability-analyze-${skill}`, 'SKILL.md') + expect(existsSync(mirrorPath)).toBe(true) + expect(mirror(`pair-capability-analyze-${skill}`).toLowerCase()).toContain('output-only') }) } }) -describe('assess-debt has no scan-mode and never auto-creates (#224)', () => { +describe('analyze-debt has no scan-mode and never auto-creates (#224)', () => { it('exposes no $mode argument (no scan-mode)', () => { - const content = dataset('debt') + const content = dataset('analyze-debt') // No $mode argument row in the Arguments table. expect(content).not.toMatch(/\|\s*`\$mode`/) }) it('states it creates no backlog items and never blocks', () => { - const content = dataset('debt').toLowerCase() + const content = dataset('analyze-debt').toLowerCase() expect(content).toContain('no auto-creation') expect(content).toContain('never block') }) From 9e555e287c05bb5841006b5600d623aad36a2086 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 13 Jul 2026 23:14:28 +0200 Subject: [PATCH 2/2] =?UTF-8?q?[#313]=20refactor:=20T8=20finish=20?= =?UTF-8?q?=E2=80=94=20table=20align=20+=20analyze-*=20internal=20consiste?= =?UTF-8?q?ncy=20(review)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - next capability table + review Composed-Skills table re-padded (GFM columns align; pre-existing raggedness cleaned) - analyze-debt/analyze-code-quality (dataset + mirror): skill's own action/output labels assess→analyze (TECH DEBT ASSESSMENT→ANALYSIS, Path B/C Existing/Full Analysis, Re-analyze, RESULT Analyzed, Notes) - Left generic/shared: cascade tier "(Argument > Adoption > Assessment)", "Assess Impact/Effort" scoring verbs, "Risk assessment", "Severity assessment" - dataset↔mirror byte-consistent under transform; gates green Refs: #313 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../SKILL.md | 24 ++++----- .../pair-capability-analyze-debt/SKILL.md | 28 +++++----- .claude/skills/pair-next/SKILL.md | 54 +++++++++---------- .claude/skills/pair-process-review/SKILL.md | 18 +++---- .../capability/analyze-code-quality/SKILL.md | 24 ++++----- .../.skills/capability/analyze-debt/SKILL.md | 28 +++++----- .../dataset/.skills/next/SKILL.md | 54 +++++++++---------- .../dataset/.skills/process/review/SKILL.md | 18 +++---- 8 files changed, 124 insertions(+), 124 deletions(-) diff --git a/.claude/skills/pair-capability-analyze-code-quality/SKILL.md b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md index 5fba1c8c..f7b986d7 100644 --- a/.claude/skills/pair-capability-analyze-code-quality/SKILL.md +++ b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md @@ -13,8 +13,8 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------------------------- | -| `$scope` | No | Limit assessment to specific metric group: `complexity`, `size`, `coverage`, `duplication`, `maintainability`, `all` (default: `all`) | -| `$path` | No | Limit assessment to a specific file, directory, or package. If omitted, assesses the full codebase. | +| `$scope` | No | Limit analysis to specific metric group: `complexity`, `size`, `coverage`, `duplication`, `maintainability`, `all` (default: `all`) | +| `$path` | No | Limit analysis to a specific file, directory, or package. If omitted, analyzes the full codebase. | ## Algorithm @@ -22,19 +22,19 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p #### Path A — Existing Recent Report -1. **Check**: Is there an existing quality report for this codebase? (Check conversation context, CI artifacts, or previous assessment output.) +1. **Check**: Is there an existing quality report for this codebase? (Check conversation context, CI artifacts, or previous analysis output.) 2. **Skip**: If no existing report, go to Path B. 3. **Act**: Check staleness: - - Has the codebase changed since the last assessment? (Use `git diff --stat` since last assessment date or commit.) + - Has the codebase changed since the last analysis? (Use `git diff --stat` since last analysis date or commit.) - If no changes → confirm existing report is still valid. Exit. - If changes exist → report is stale. Present summary of changes and proceed to Path B. - > Existing quality report found ([date]). [N files changed since last assessment.] - > Re-assess? (Recommended — codebase has changed.) + > Existing quality report found ([date]). [N files changed since last analysis.] + > Re-analyze? (Recommended — codebase has changed.) -4. **Verify**: If confirmed valid → exit. If stale or re-assessment requested → proceed to Path B. +4. **Verify**: If confirmed valid → exit. If stale or re-analysis requested → proceed to Path B. -#### Path B — Full Assessment +#### Path B — Full Analysis 1. **Act**: Proceed to Step 2. @@ -134,7 +134,7 @@ RECOMMENDATIONS: 1. [priority] [metric] — [current] → [target]: [action] 2. ... -RESULT: [Quality score: N/100 | Assessed | Confirmed existing] +RESULT: [Quality score: N/100 | Analyzed | Confirmed existing] ``` ## Composition Interface @@ -160,7 +160,7 @@ When invoked **independently**: ## Notes - This skill is **read-only / output-only** — it inspects code, runs coverage (via existing test commands), but never modifies files, adoption, or the PM tool. A finding worth tracking is promoted deliberately to the backlog via `/pair-capability-write-issue` (a manual, selective act) — never auto-created. -- **Idempotent**: re-invocation checks staleness of existing report. If codebase unchanged → confirms existing report. If changed → re-assesses only. +- **Idempotent**: re-invocation checks staleness of existing report. If codebase unchanged → confirms existing report. If changed → re-analyzes only. - 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. +- 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 873d91f8..573a4256 100644 --- a/.claude/skills/pair-capability-analyze-debt/SKILL.md +++ b/.claude/skills/pair-capability-analyze-debt/SKILL.md @@ -13,8 +13,8 @@ Detect, categorize, and prioritize technical debt items. Applies the prioritizat | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `$scope` | No | Limit assessment to specific categories: `code`, `design`, `test`, `documentation`, `infrastructure`, `all` (default: `all`) | -| `$choice`| No | Pre-identified debt item to assess (e.g., `"missing error handling in API layer"`). Skips detection, goes directly to categorization and scoring. | +| `$scope` | No | Limit analysis to specific categories: `code`, `design`, `test`, `documentation`, `infrastructure`, `all` (default: `all`) | +| `$choice`| No | Pre-identified debt item to analyze (e.g., `"missing error handling in API layer"`). Skips detection, goes directly to categorization and scoring. | ## Composed Skills @@ -31,18 +31,18 @@ This skill is **output-only** — it composes no skill and writes no files. No a 3. **Act**: Accept the pre-identified debt item. Skip detection (Step 2). Proceed directly to Step 3 (categorization) with the single item. 4. **Verify**: Item accepted. -#### Path B — Existing Assessment +#### Path B — Existing Analysis -1. **Check**: Is there an existing debt assessment for this codebase/PR? (Look for a recent debt report in the conversation context or PR comments.) -2. **Skip**: If no existing assessment, go to Path C. -3. **Act**: Present the existing assessment: +1. **Check**: Is there an existing debt analysis for this codebase/PR? (Look for a recent debt report in the conversation context or PR comments.) +2. **Skip**: If no existing analysis, go to Path C. +3. **Act**: Present the existing analysis: - > Existing debt assessment found ([N items], [date]). - > Re-assess? (Only if explicitly requested by developer.) + > Existing debt analysis found ([N items], [date]). + > Re-analyze? (Only if explicitly requested by developer.) -4. **Verify**: If developer confirms existing → exit. If re-assessment requested → proceed to Path C. +4. **Verify**: If developer confirms existing → exit. If re-analysis requested → proceed to Path C. -#### Path C — Full Assessment +#### Path C — Full Analysis 1. **Act**: Proceed to Step 2 (detection). @@ -150,7 +150,7 @@ For each detected item, apply the prioritization formula: ## Output Format ```text -TECH DEBT ASSESSMENT (output-only — no files or issues created): +TECH DEBT ANALYSIS (output-only — no files or issues created): ├── Items Found: [N total] ├── Categories: Code: [N] | Design: [N] | Test: [N] | Docs: [N] | Infra: [N] ├── Severity: High: [N] | Medium: [N] | Low: [N] @@ -166,7 +166,7 @@ REMEDIATION PLAN (High severity): 1. [item] — [strategy] (est. [effort]) 2. ... -RESULT: [N items assessed, N high-priority — report only, nothing created/blocked] +RESULT: [N items analyzed, N high-priority — report only, nothing created/blocked] ``` ## Composition Interface @@ -174,7 +174,7 @@ RESULT: [N items assessed, N high-priority — report only, nothing created/bloc When composed by `/pair-process-review`: - **Input**: /pair-process-review invokes `/pair-capability-analyze-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). +- **Output**: Returns the debt 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. - /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. @@ -192,6 +192,6 @@ When invoked **independently**: ## Notes -- **Idempotent**: re-invocation on an already-assessed codebase confirms the existing assessment. Re-assessment only on explicit developer request. +- **Idempotent**: re-invocation on an already-analyzed codebase confirms the existing analysis. Re-analysis only on explicit developer request. - 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-next/SKILL.md b/.claude/skills/pair-next/SKILL.md index 4276d8c6..ad3d0871 100644 --- a/.claude/skills/pair-next/SKILL.md +++ b/.claude/skills/pair-next/SKILL.md @@ -29,33 +29,33 @@ The catalog is **derived from the installed corpus**: every installed skill must ### Capability Skills (25) -| Skill | Category | Description | -| -------------------- | ------------ | ----------------------------------------------- | -| `/pair-capability-map-subdomains` | Domain Modeling | Scoped DDD subdomain placement (+ Volatility) | -| `/pair-capability-map-contexts` | Domain Modeling | Scoped DDD bounded-context placement + relationship assessment | -| `/pair-capability-grill` | Alignment | Interview engine: explore a topic or sync on a story, one question at a time | -| `/pair-capability-record-decision` | Decision | Record ADR or ADL with adoption update | -| `/pair-capability-checkpoint` | Session State | Write/resume story progress checkpoint (work survives context resets) | -| `/pair-capability-write-issue` | PM Tool | Create/update issues in adopted PM tool | -| `/pair-capability-setup-pm` | PM Tool | Configure project management tool | -| `/pair-capability-verify-quality` | Quality | Check quality gates against codebase | -| `/pair-capability-verify-done` | Quality | Check Definition of Done criteria | -| `/pair-capability-verify-adoption` | Quality | Check code against adoption files per scope | -| `/pair-capability-assess-stack` | Assessment | Assess tech stack (lifecycle-spanning) | -| `/pair-capability-assess-architecture`| Assessment | Assess architecture pattern | -| `/pair-capability-assess-testing` | Assessment | Assess testing strategy | -| `/pair-capability-assess-ai` | Assessment | Assess AI development tools | -| `/pair-capability-assess-methodology`| Assessment | Assess development methodology | -| `/pair-capability-assess-pm` | Assessment | Assess project management tool | -| `/pair-capability-assess-infrastructure`| Assessment| Assess infrastructure strategy | -| `/pair-capability-assess-observability`| Assessment | Assess observability strategy | -| `/pair-capability-analyze-debt` | Analysis | Analyze technical debt with prioritization | -| `/pair-capability-analyze-code-quality`| Analysis | Analyze code quality with metrics | -| `/pair-capability-estimate` | Planning | Estimate story using adopted methodology | -| `/pair-capability-setup-gates` | Configuration| Configure CI/CD quality gates | -| `/pair-capability-manage-flags` | Configuration| Manage feature flag lifecycle | -| `/pair-capability-design-manual-tests`| Testing | Generate manual test suite from project analysis| -| `/pair-capability-execute-manual-tests`| Testing | Execute manual test suite + generate report | +| Skill | Category | Description | +| ---------------------------------------- | --------------- | ---------------------------------------------------------------------------- | +| `/pair-capability-map-subdomains` | Domain Modeling | Scoped DDD subdomain placement (+ Volatility) | +| `/pair-capability-map-contexts` | Domain Modeling | Scoped DDD bounded-context placement + relationship assessment | +| `/pair-capability-grill` | Alignment | Interview engine: explore a topic or sync on a story, one question at a time | +| `/pair-capability-record-decision` | Decision | Record ADR or ADL with adoption update | +| `/pair-capability-checkpoint` | Session State | Write/resume story progress checkpoint (work survives context resets) | +| `/pair-capability-write-issue` | PM Tool | Create/update issues in adopted PM tool | +| `/pair-capability-setup-pm` | PM Tool | Configure project management tool | +| `/pair-capability-verify-quality` | Quality | Check quality gates against codebase | +| `/pair-capability-verify-done` | Quality | Check Definition of Done criteria | +| `/pair-capability-verify-adoption` | Quality | Check code against adoption files per scope | +| `/pair-capability-assess-stack` | Assessment | Assess tech stack (lifecycle-spanning) | +| `/pair-capability-assess-architecture` | Assessment | Assess architecture pattern | +| `/pair-capability-assess-testing` | Assessment | Assess testing strategy | +| `/pair-capability-assess-ai` | Assessment | Assess AI development tools | +| `/pair-capability-assess-methodology` | Assessment | Assess development methodology | +| `/pair-capability-assess-pm` | Assessment | Assess project management tool | +| `/pair-capability-assess-infrastructure` | Assessment | Assess infrastructure strategy | +| `/pair-capability-assess-observability` | Assessment | Assess observability strategy | +| `/pair-capability-analyze-debt` | Analysis | Analyze technical debt with prioritization | +| `/pair-capability-analyze-code-quality` | Analysis | Analyze code quality with metrics | +| `/pair-capability-estimate` | Planning | Estimate story using adopted methodology | +| `/pair-capability-setup-gates` | Configuration | Configure CI/CD quality gates | +| `/pair-capability-manage-flags` | Configuration | Manage feature flag lifecycle | +| `/pair-capability-design-manual-tests` | Testing | Generate manual test suite from project analysis | +| `/pair-capability-execute-manual-tests` | Testing | Execute manual test suite + generate report | ## Algorithm diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index ee0f8bfd..48159899 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -11,15 +11,15 @@ Review a pull request through 6 sequential phases (5 review + 1 optional merge). ## Composed Skills -| Skill | Type | Required | Phase | Purpose | -| ------------------ | ---------- | -------- | ----- | ------------------------------------ | -| `/pair-capability-verify-quality` | Capability | Yes | 2 | Quality gate checking | -| `/pair-capability-verify-done` | Capability | Yes | 4 | Definition of Done checking | -| `/pair-capability-record-decision` | Capability | Yes | Any | Record missing ADR (HALT condition) | -| `/pair-capability-analyze-debt` | Capability | Yes | 4 | Flag tech debt items | -| `/pair-capability-verify-adoption` | Capability | Optional | 3 | Full adoption compliance | -| `/pair-capability-assess-stack` | Capability | Optional | 3 | Tech-stack resolution | -| `/pair-capability-execute-manual-tests` | Capability | Optional | 6 | Post-merge release validation (manual tests) | +| Skill | Type | Required | Phase | Purpose | +| --------------------------------------- | ---------- | -------- | ----- | -------------------------------------------- | +| `/pair-capability-verify-quality` | Capability | Yes | 2 | Quality gate checking | +| `/pair-capability-verify-done` | Capability | Yes | 4 | Definition of Done checking | +| `/pair-capability-record-decision` | Capability | Yes | Any | Record missing ADR (HALT condition) | +| `/pair-capability-analyze-debt` | Capability | Yes | 4 | Flag tech debt items | +| `/pair-capability-verify-adoption` | Capability | Optional | 3 | Full adoption compliance | +| `/pair-capability-assess-stack` | Capability | Optional | 3 | Tech-stack resolution | +| `/pair-capability-execute-manual-tests` | Capability | Optional | 6 | Post-merge release validation (manual tests) | ## Arguments 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 23af276b..967e0953 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 @@ -13,8 +13,8 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------------------------- | -| `$scope` | No | Limit assessment to specific metric group: `complexity`, `size`, `coverage`, `duplication`, `maintainability`, `all` (default: `all`) | -| `$path` | No | Limit assessment to a specific file, directory, or package. If omitted, assesses the full codebase. | +| `$scope` | No | Limit analysis to specific metric group: `complexity`, `size`, `coverage`, `duplication`, `maintainability`, `all` (default: `all`) | +| `$path` | No | Limit analysis to a specific file, directory, or package. If omitted, analyzes the full codebase. | ## Algorithm @@ -22,19 +22,19 @@ Evaluate code quality using objective metrics from [code-metrics.md](../../../.p #### Path A — Existing Recent Report -1. **Check**: Is there an existing quality report for this codebase? (Check conversation context, CI artifacts, or previous assessment output.) +1. **Check**: Is there an existing quality report for this codebase? (Check conversation context, CI artifacts, or previous analysis output.) 2. **Skip**: If no existing report, go to Path B. 3. **Act**: Check staleness: - - Has the codebase changed since the last assessment? (Use `git diff --stat` since last assessment date or commit.) + - Has the codebase changed since the last analysis? (Use `git diff --stat` since last analysis date or commit.) - If no changes → confirm existing report is still valid. Exit. - If changes exist → report is stale. Present summary of changes and proceed to Path B. - > Existing quality report found ([date]). [N files changed since last assessment.] - > Re-assess? (Recommended — codebase has changed.) + > Existing quality report found ([date]). [N files changed since last analysis.] + > Re-analyze? (Recommended — codebase has changed.) -4. **Verify**: If confirmed valid → exit. If stale or re-assessment requested → proceed to Path B. +4. **Verify**: If confirmed valid → exit. If stale or re-analysis requested → proceed to Path B. -#### Path B — Full Assessment +#### Path B — Full Analysis 1. **Act**: Proceed to Step 2. @@ -134,7 +134,7 @@ RECOMMENDATIONS: 1. [priority] [metric] — [current] → [target]: [action] 2. ... -RESULT: [Quality score: N/100 | Assessed | Confirmed existing] +RESULT: [Quality score: N/100 | Analyzed | Confirmed existing] ``` ## Composition Interface @@ -160,7 +160,7 @@ When invoked **independently**: ## Notes - This skill is **read-only / output-only** — it inspects code, runs coverage (via existing test commands), but never modifies files, adoption, or the PM tool. A finding worth tracking is promoted deliberately to the backlog via `/write-issue` (a manual, selective act) — never auto-created. -- **Idempotent**: re-invocation checks staleness of existing report. If codebase unchanged → confirms existing report. If changed → re-assesses only. +- **Idempotent**: re-invocation checks staleness of existing report. If codebase unchanged → confirms existing report. If changed → re-analyzes only. - 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. +- 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 ae51f8b5..b435abee 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md @@ -13,8 +13,8 @@ Detect, categorize, and prioritize technical debt items. Applies the prioritizat | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `$scope` | No | Limit assessment to specific categories: `code`, `design`, `test`, `documentation`, `infrastructure`, `all` (default: `all`) | -| `$choice`| No | Pre-identified debt item to assess (e.g., `"missing error handling in API layer"`). Skips detection, goes directly to categorization and scoring. | +| `$scope` | No | Limit analysis to specific categories: `code`, `design`, `test`, `documentation`, `infrastructure`, `all` (default: `all`) | +| `$choice`| No | Pre-identified debt item to analyze (e.g., `"missing error handling in API layer"`). Skips detection, goes directly to categorization and scoring. | ## Composed Skills @@ -31,18 +31,18 @@ This skill is **output-only** — it composes no skill and writes no files. No a 3. **Act**: Accept the pre-identified debt item. Skip detection (Step 2). Proceed directly to Step 3 (categorization) with the single item. 4. **Verify**: Item accepted. -#### Path B — Existing Assessment +#### Path B — Existing Analysis -1. **Check**: Is there an existing debt assessment for this codebase/PR? (Look for a recent debt report in the conversation context or PR comments.) -2. **Skip**: If no existing assessment, go to Path C. -3. **Act**: Present the existing assessment: +1. **Check**: Is there an existing debt analysis for this codebase/PR? (Look for a recent debt report in the conversation context or PR comments.) +2. **Skip**: If no existing analysis, go to Path C. +3. **Act**: Present the existing analysis: - > Existing debt assessment found ([N items], [date]). - > Re-assess? (Only if explicitly requested by developer.) + > Existing debt analysis found ([N items], [date]). + > Re-analyze? (Only if explicitly requested by developer.) -4. **Verify**: If developer confirms existing → exit. If re-assessment requested → proceed to Path C. +4. **Verify**: If developer confirms existing → exit. If re-analysis requested → proceed to Path C. -#### Path C — Full Assessment +#### Path C — Full Analysis 1. **Act**: Proceed to Step 2 (detection). @@ -150,7 +150,7 @@ For each detected item, apply the prioritization formula: ## Output Format ```text -TECH DEBT ASSESSMENT (output-only — no files or issues created): +TECH DEBT ANALYSIS (output-only — no files or issues created): ├── Items Found: [N total] ├── Categories: Code: [N] | Design: [N] | Test: [N] | Docs: [N] | Infra: [N] ├── Severity: High: [N] | Medium: [N] | Low: [N] @@ -166,7 +166,7 @@ REMEDIATION PLAN (High severity): 1. [item] — [strategy] (est. [effort]) 2. ... -RESULT: [N items assessed, N high-priority — report only, nothing created/blocked] +RESULT: [N items analyzed, N high-priority — report only, nothing created/blocked] ``` ## Composition Interface @@ -174,7 +174,7 @@ RESULT: [N items assessed, N high-priority — report only, nothing created/bloc When composed by `/review`: - **Input**: /review invokes `/analyze-debt` during the completeness phase (Phase 4). -- **Output**: Returns the debt assessment report. /review incorporates findings into review output (the Tech Debt section). +- **Output**: Returns the debt report. /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. - /review does **not** auto-create tech-debt issues. Items worth tracking are promoted deliberately (after review) via `/write-issue` with the `tech-debt` label. @@ -192,6 +192,6 @@ When invoked **independently**: ## Notes -- **Idempotent**: re-invocation on an already-assessed codebase confirms the existing assessment. Re-assessment only on explicit developer request. +- **Idempotent**: re-invocation on an already-analyzed codebase confirms the existing analysis. Re-analysis only on explicit developer request. - 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/next/SKILL.md b/packages/knowledge-hub/dataset/.skills/next/SKILL.md index e7205f50..43c428fa 100644 --- a/packages/knowledge-hub/dataset/.skills/next/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/next/SKILL.md @@ -29,33 +29,33 @@ The catalog is **derived from the installed corpus**: every skill directory unde ### Capability Skills (25) -| Skill | Category | Description | -| -------------------- | ------------ | ----------------------------------------------- | -| `/map-subdomains` | Domain Modeling | Scoped DDD subdomain placement (+ Volatility) | -| `/map-contexts` | Domain Modeling | Scoped DDD bounded-context placement + relationship assessment | -| `/grill` | Alignment | Interview engine: explore a topic or sync on a story, one question at a time | -| `/record-decision` | Decision | Record ADR or ADL with adoption update | -| `/checkpoint` | Session State | Write/resume story progress checkpoint (work survives context resets) | -| `/write-issue` | PM Tool | Create/update issues in adopted PM tool | -| `/setup-pm` | PM Tool | Configure project management tool | -| `/verify-quality` | Quality | Check quality gates against codebase | -| `/verify-done` | Quality | Check Definition of Done criteria | -| `/verify-adoption` | Quality | Check code against adoption files per scope | -| `/assess-stack` | Assessment | Assess tech stack (lifecycle-spanning) | -| `/assess-architecture`| Assessment | Assess architecture pattern | -| `/assess-testing` | Assessment | Assess testing strategy | -| `/assess-ai` | Assessment | Assess AI development tools | -| `/assess-methodology`| Assessment | Assess development methodology | -| `/assess-pm` | Assessment | Assess project management tool | -| `/assess-infrastructure`| Assessment| Assess infrastructure strategy | -| `/assess-observability`| Assessment | Assess observability strategy | -| `/analyze-debt` | Analysis | Analyze technical debt with prioritization | -| `/analyze-code-quality`| Analysis | Analyze code quality with metrics | -| `/estimate` | Planning | Estimate story using adopted methodology | -| `/setup-gates` | Configuration| Configure CI/CD quality gates | -| `/manage-flags` | Configuration| Manage feature flag lifecycle | -| `/design-manual-tests`| Testing | Generate manual test suite from project analysis| -| `/execute-manual-tests`| Testing | Execute manual test suite + generate report | +| Skill | Category | Description | +| ------------------------ | --------------- | ---------------------------------------------------------------------------- | +| `/map-subdomains` | Domain Modeling | Scoped DDD subdomain placement (+ Volatility) | +| `/map-contexts` | Domain Modeling | Scoped DDD bounded-context placement + relationship assessment | +| `/grill` | Alignment | Interview engine: explore a topic or sync on a story, one question at a time | +| `/record-decision` | Decision | Record ADR or ADL with adoption update | +| `/checkpoint` | Session State | Write/resume story progress checkpoint (work survives context resets) | +| `/write-issue` | PM Tool | Create/update issues in adopted PM tool | +| `/setup-pm` | PM Tool | Configure project management tool | +| `/verify-quality` | Quality | Check quality gates against codebase | +| `/verify-done` | Quality | Check Definition of Done criteria | +| `/verify-adoption` | Quality | Check code against adoption files per scope | +| `/assess-stack` | Assessment | Assess tech stack (lifecycle-spanning) | +| `/assess-architecture` | Assessment | Assess architecture pattern | +| `/assess-testing` | Assessment | Assess testing strategy | +| `/assess-ai` | Assessment | Assess AI development tools | +| `/assess-methodology` | Assessment | Assess development methodology | +| `/assess-pm` | Assessment | Assess project management tool | +| `/assess-infrastructure` | Assessment | Assess infrastructure strategy | +| `/assess-observability` | Assessment | Assess observability strategy | +| `/analyze-debt` | Analysis | Analyze technical debt with prioritization | +| `/analyze-code-quality` | Analysis | Analyze code quality with metrics | +| `/estimate` | Planning | Estimate story using adopted methodology | +| `/setup-gates` | Configuration | Configure CI/CD quality gates | +| `/manage-flags` | Configuration | Manage feature flag lifecycle | +| `/design-manual-tests` | Testing | Generate manual test suite from project analysis | +| `/execute-manual-tests` | Testing | Execute manual test suite + generate report | ## Algorithm diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index f63b2e83..0ed0a177 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -11,15 +11,15 @@ Review a pull request through 6 sequential phases (5 review + 1 optional merge). ## Composed Skills -| Skill | Type | Required | Phase | Purpose | -| ------------------ | ---------- | -------- | ----- | ------------------------------------ | -| `/verify-quality` | Capability | Yes | 2 | Quality gate checking | -| `/verify-done` | Capability | Yes | 4 | Definition of Done checking | -| `/record-decision` | Capability | Yes | Any | Record missing ADR (HALT condition) | -| `/analyze-debt` | Capability | Yes | 4 | Flag tech debt items | -| `/verify-adoption` | Capability | Optional | 3 | Full adoption compliance | -| `/assess-stack` | Capability | Optional | 3 | Tech-stack resolution | -| `/execute-manual-tests` | Capability | Optional | 6 | Post-merge release validation (manual tests) | +| Skill | Type | Required | Phase | Purpose | +| ----------------------- | ---------- | -------- | ----- | -------------------------------------------- | +| `/verify-quality` | Capability | Yes | 2 | Quality gate checking | +| `/verify-done` | Capability | Yes | 4 | Definition of Done checking | +| `/record-decision` | Capability | Yes | Any | Record missing ADR (HALT condition) | +| `/analyze-debt` | Capability | Yes | 4 | Flag tech debt items | +| `/verify-adoption` | Capability | Optional | 3 | Full adoption compliance | +| `/assess-stack` | Capability | Optional | 3 | Tech-stack resolution | +| `/execute-manual-tests` | Capability | Optional | 6 | Post-merge release validation (manual tests) | ## Arguments