From 48c8746ec168c838f98ac7c19ac4fc1dc855fc1b Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 13 Jul 2026 23:48:25 +0200 Subject: [PATCH 1/2] [#313] refactor: trigger-oriented descriptions for all 35 skills (task T3) Rewrite all 34 non-conformant frontmatter descriptions (next already conformant) per the T2 authoring standard: trigger branches over body-identity restatement, reach clauses for mostly-composed capabilities, assess-pm vs setup-pm and assess-stack vs verify-adoption disambiguated by verb (recommend/configure) and by already-written vs proposed. Sync skills-catalog.mdx description column. Eval before/after in packages/knowledge-hub/eval/results/2026-07-13-after-t3.md: 96.2% -> 100% (79/79), 0 regressions, all 3 baseline ambiguities resolved. Co-Authored-By: Claude Code --- .../SKILL.md | 2 +- .../pair-capability-analyze-debt/SKILL.md | 2 +- .../skills/pair-capability-assess-ai/SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../skills/pair-capability-assess-pm/SKILL.md | 2 +- .../pair-capability-assess-stack/SKILL.md | 2 +- .../pair-capability-assess-testing/SKILL.md | 2 +- .../pair-capability-checkpoint/SKILL.md | 2 +- .../SKILL.md | 2 +- .../skills/pair-capability-estimate/SKILL.md | 2 +- .../SKILL.md | 2 +- .claude/skills/pair-capability-grill/SKILL.md | 2 +- .../pair-capability-manage-flags/SKILL.md | 2 +- .../pair-capability-map-contexts/SKILL.md | 2 +- .../pair-capability-map-subdomains/SKILL.md | 2 +- .../pair-capability-record-decision/SKILL.md | 2 +- .../pair-capability-setup-gates/SKILL.md | 2 +- .../skills/pair-capability-setup-pm/SKILL.md | 2 +- .../pair-capability-verify-adoption/SKILL.md | 2 +- .../pair-capability-verify-done/SKILL.md | 2 +- .../pair-capability-verify-quality/SKILL.md | 2 +- .../pair-capability-write-issue/SKILL.md | 2 +- .../skills/pair-process-bootstrap/SKILL.md | 2 +- .../skills/pair-process-implement/SKILL.md | 2 +- .../skills/pair-process-plan-epics/SKILL.md | 2 +- .../pair-process-plan-initiatives/SKILL.md | 2 +- .../skills/pair-process-plan-stories/SKILL.md | 2 +- .../skills/pair-process-plan-tasks/SKILL.md | 2 +- .../skills/pair-process-refine-story/SKILL.md | 2 +- .claude/skills/pair-process-review/SKILL.md | 2 +- .../skills/pair-process-specify-prd/SKILL.md | 2 +- .../content/docs/reference/skills-catalog.mdx | 68 ++--- .../capability/analyze-code-quality/SKILL.md | 2 +- .../.skills/capability/analyze-debt/SKILL.md | 2 +- .../.skills/capability/assess-ai/SKILL.md | 2 +- .../capability/assess-architecture/SKILL.md | 2 +- .../capability/assess-infrastructure/SKILL.md | 2 +- .../capability/assess-methodology/SKILL.md | 2 +- .../capability/assess-observability/SKILL.md | 2 +- .../.skills/capability/assess-pm/SKILL.md | 2 +- .../.skills/capability/assess-stack/SKILL.md | 2 +- .../capability/assess-testing/SKILL.md | 2 +- .../.skills/capability/checkpoint/SKILL.md | 2 +- .../capability/design-manual-tests/SKILL.md | 2 +- .../.skills/capability/estimate/SKILL.md | 2 +- .../capability/execute-manual-tests/SKILL.md | 2 +- .../dataset/.skills/capability/grill/SKILL.md | 2 +- .../.skills/capability/manage-flags/SKILL.md | 2 +- .../.skills/capability/map-contexts/SKILL.md | 2 +- .../capability/map-subdomains/SKILL.md | 2 +- .../capability/record-decision/SKILL.md | 2 +- .../.skills/capability/setup-gates/SKILL.md | 2 +- .../.skills/capability/setup-pm/SKILL.md | 2 +- .../capability/verify-adoption/SKILL.md | 2 +- .../.skills/capability/verify-done/SKILL.md | 2 +- .../capability/verify-quality/SKILL.md | 2 +- .../.skills/capability/write-issue/SKILL.md | 2 +- .../.skills/process/bootstrap/SKILL.md | 2 +- .../.skills/process/implement/SKILL.md | 2 +- .../.skills/process/plan-epics/SKILL.md | 2 +- .../.skills/process/plan-initiatives/SKILL.md | 2 +- .../.skills/process/plan-stories/SKILL.md | 2 +- .../.skills/process/plan-tasks/SKILL.md | 2 +- .../.skills/process/refine-story/SKILL.md | 2 +- .../dataset/.skills/process/review/SKILL.md | 2 +- .../.skills/process/specify-prd/SKILL.md | 2 +- .../eval/results/2026-07-13-after-t3.md | 274 ++++++++++++++++++ 70 files changed, 376 insertions(+), 102 deletions(-) create mode 100644 packages/knowledge-hub/eval/results/2026-07-13-after-t3.md diff --git a/.claude/skills/pair-capability-analyze-code-quality/SKILL.md b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md index f7b986d7..ff058b78 100644 --- a/.claude/skills/pair-capability-analyze-code-quality/SKILL.md +++ b/.claude/skills/pair-capability-analyze-code-quality/SKILL.md @@ -1,6 +1,6 @@ --- 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." +description: "Produces an objective code quality report — complexity, size, coverage, duplication, maintainability score — for a repo or package, with actionable recommendations. Composed by /pair-process-review; invoke directly for a report on demand ('code quality report', 'how maintainable is this'). Output-only: writes nothing, never blocks." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-analyze-debt/SKILL.md b/.claude/skills/pair-capability-analyze-debt/SKILL.md index 573a4256..60efa5e5 100644 --- a/.claude/skills/pair-capability-analyze-debt/SKILL.md +++ b/.claude/skills/pair-capability-analyze-debt/SKILL.md @@ -1,6 +1,6 @@ --- 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." +description: "Produces a technical debt report — categorized items (code, design, test, documentation, infrastructure), prioritized by impact x effort. Composed by /pair-process-review; invoke directly to catalog and prioritize debt on demand. Output-only: writes no files, creates no backlog items, never blocks a PR." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-assess-ai/SKILL.md b/.claude/skills/pair-capability-assess-ai/SKILL.md index e3f28ce0..233c543b 100644 --- a/.claude/skills/pair-capability-assess-ai/SKILL.md +++ b/.claude/skills/pair-capability-assess-ai/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-ai -description: "Assess AI development tools using resolution cascade (Argument > Adoption > Assessment). Reads AI development guidelines, proposes AI tool choices with versions and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /pair-capability-record-decision. Idempotent." +description: "Evaluates and recommends AI development tools — coding assistants (Copilot, Claude Code, Cursor), agent frameworks, MCP integrations, models — when the choice is open. Output-only: emits a proposal + target for /pair-capability-record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-assess-architecture/SKILL.md b/.claude/skills/pair-capability-assess-architecture/SKILL.md index 2e0daf33..e2931782 100644 --- a/.claude/skills/pair-capability-assess-architecture/SKILL.md +++ b/.claude/skills/pair-capability-assess-architecture/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-architecture -description: "Assess architecture pattern using resolution cascade (Argument > Adoption > Assessment). Reads architecture guidelines, proposes a pattern and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /pair-capability-record-decision. Idempotent." +description: "Evaluates and recommends an architecture pattern (layered, hexagonal, microservices, modular monolith, etc.) when the choice is open. Output-only: emits a proposal + target for /pair-capability-record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-assess-infrastructure/SKILL.md b/.claude/skills/pair-capability-assess-infrastructure/SKILL.md index 16e69185..2a8b3381 100644 --- a/.claude/skills/pair-capability-assess-infrastructure/SKILL.md +++ b/.claude/skills/pair-capability-assess-infrastructure/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-infrastructure -description: "Assess infrastructure strategy using resolution cascade (Argument > Adoption > Assessment). Reads infrastructure guidelines, proposes cloud/CI/CD/deployment choices and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /pair-capability-record-decision. Idempotent." +description: "Evaluates and recommends infrastructure strategy — cloud provider, CI/CD pipeline, deployment pattern, IaC, environments — when the choice is open. Output-only: emits a proposal + target for /pair-capability-record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-assess-methodology/SKILL.md b/.claude/skills/pair-capability-assess-methodology/SKILL.md index 90e7f57f..f46d2dbf 100644 --- a/.claude/skills/pair-capability-assess-methodology/SKILL.md +++ b/.claude/skills/pair-capability-assess-methodology/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-methodology -description: "Assess development methodology using resolution cascade (Argument > Adoption > Assessment). Reads methodology guidelines, proposes Scrum/Kanban/Lean/etc. and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /pair-capability-record-decision. Idempotent." +description: "Evaluates and recommends the development methodology (Scrum, Kanban, Lean, SAFe, hybrid) — iterations, ceremonies, flow — when the choice is open. Output-only: emits a proposal + target for /pair-capability-record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-assess-observability/SKILL.md b/.claude/skills/pair-capability-assess-observability/SKILL.md index 1da7dee5..517fd590 100644 --- a/.claude/skills/pair-capability-assess-observability/SKILL.md +++ b/.claude/skills/pair-capability-assess-observability/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-observability -description: "Assess observability strategy using resolution cascade (Argument > Adoption > Assessment). Reads observability guidelines, proposes monitoring/logging/tracing choices and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /pair-capability-record-decision. Idempotent." +description: "Evaluates and recommends the observability strategy — monitoring, logging, tracing, alerting, telemetry — when the choice is open. Output-only: emits a proposal + target for /pair-capability-record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-assess-pm/SKILL.md b/.claude/skills/pair-capability-assess-pm/SKILL.md index 06411d4c..a368f8d9 100644 --- a/.claude/skills/pair-capability-assess-pm/SKILL.md +++ b/.claude/skills/pair-capability-assess-pm/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-pm -description: "Assess project management tool using resolution cascade (Argument > Adoption > Assessment). Reads PM tool guidelines, proposes a tool choice and emits rendered adoption content + target (output-only, writes nothing); persistence via /pair-capability-setup-pm or the caller's /pair-capability-record-decision. Idempotent." +description: "Evaluates and recommends which project management tool fits this project (Jira, Linear, GitHub Projects, etc.) when the choice is still open — proposes a choice, doesn't configure anything. /pair-capability-setup-pm configures the tool once picked; otherwise the caller persists the proposal via /pair-capability-record-decision." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-assess-stack/SKILL.md b/.claude/skills/pair-capability-assess-stack/SKILL.md index 782b39ea..2913c86b 100644 --- a/.claude/skills/pair-capability-assess-stack/SKILL.md +++ b/.claude/skills/pair-capability-assess-stack/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-stack -description: "Assess tech stack using resolution cascade (Argument > Adoption > Assessment). Lifecycle-spanning: bootstrap (full eval), implementation (add dependency), review (detect unlisted). Version tracking. Output-only: emits rendered adoption content + target; the caller persists via /pair-capability-record-decision. Idempotent." +description: "Evaluates and recommends the tech stack — languages, frameworks, database, libraries, versions — when the choice is open: full evaluation at bootstrap, or a single new dependency during implementation ('should we add Redis', 'is this new dependency consistent with our stack'). Doesn't audit code already written (that's /pair-capability-verify-adoption). Output-only: emits a proposal + target for /pair-capability-record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-assess-testing/SKILL.md b/.claude/skills/pair-capability-assess-testing/SKILL.md index bf41397d..5a619bdd 100644 --- a/.claude/skills/pair-capability-assess-testing/SKILL.md +++ b/.claude/skills/pair-capability-assess-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-testing -description: "Assess testing strategy using resolution cascade (Argument > Adoption > Assessment). Reads testing guidelines, proposes framework and strategy and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /pair-capability-record-decision. Idempotent." +description: "Evaluates and recommends the testing strategy — framework, pyramid distribution, coverage targets, TDD approach — when the choice is open. Doesn't write tests itself. Output-only: emits a proposal + target for /pair-capability-record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-checkpoint/SKILL.md b/.claude/skills/pair-capability-checkpoint/SKILL.md index 1dd2ecf9..0e570da6 100644 --- a/.claude/skills/pair-capability-checkpoint/SKILL.md +++ b/.claude/skills/pair-capability-checkpoint/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-checkpoint -description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives context resets. Write mode persists state to .pair/working/checkpoints/.md, one file per story; resume mode locates and parses it. Invocable independently; composed by a future closing phase of /pair-process-implement and a future /pair-capability-publish-pr (planned — #255) as a handoff." +description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives a context reset. Invoke directly to save or resume progress ('save our progress on #313', 'resume story #256'); composed by a future closing phase of /pair-process-implement and a future /pair-capability-publish-pr (planned — #255)." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-design-manual-tests/SKILL.md b/.claude/skills/pair-capability-design-manual-tests/SKILL.md index 5e9ee7a6..f41d1b6c 100644 --- a/.claude/skills/pair-capability-design-manual-tests/SKILL.md +++ b/.claude/skills/pair-capability-design-manual-tests/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-design-manual-tests -description: "Designs a manual test suite for post-release validation by analyzing the project's artifacts, architecture, and deployment targets. Generates critical path files (CP*.md) and a suite README following manual-testing guidelines and the manual-test-case-template. Invocable independently or as a prerequisite of /pair-capability-execute-manual-tests." +description: "Designs a manual test suite — critical path files + suite README — for post-release validation, by analyzing released artifacts, architecture, and deployment targets. Not for planning the automated-testing approach (use /pair-capability-assess-testing). Prerequisite for /pair-capability-execute-manual-tests." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-estimate/SKILL.md b/.claude/skills/pair-capability-estimate/SKILL.md index af9ca88a..2c66d7e2 100644 --- a/.claude/skills/pair-capability-estimate/SKILL.md +++ b/.claude/skills/pair-capability-estimate/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-estimate -description: "Estimates a refined user story using the adopted estimation methodology. Reads estimation framework from guidelines and methodology from way-of-working. Idempotent: detects existing estimate, confirms rather than re-estimating. Invocable independently or composed by /pair-process-refine-story." +description: "Estimates story points for a refined user story using the project's adopted estimation methodology; confirms rather than re-estimating if already sized. Composed by /pair-process-refine-story; invoke directly to size a story on demand ('estimate story #87')." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-execute-manual-tests/SKILL.md b/.claude/skills/pair-capability-execute-manual-tests/SKILL.md index 5669bfb2..bf3b664f 100644 --- a/.claude/skills/pair-capability-execute-manual-tests/SKILL.md +++ b/.claude/skills/pair-capability-execute-manual-tests/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-execute-manual-tests -description: "Executes a project's manual test suite against released artifacts, producing a structured report. Resolves test variables, iterates through critical paths, records PASS/FAIL per test case, and generates the report from the manual-test-report template. Invocable independently or composed by /pair-process-review (post-merge validation)." +description: "Executes a project's manual test suite against released or deployed artifacts, producing a structured PASS/FAIL report per critical path. Not for running the automated test suite (use /pair-capability-verify-quality). Composed by /pair-process-review for post-merge validation." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-grill/SKILL.md b/.claude/skills/pair-capability-grill/SKILL.md index 3a64cc49..3822e1b0 100644 --- a/.claude/skills/pair-capability-grill/SKILL.md +++ b/.claude/skills/pair-capability-grill/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-grill -description: "Reusable interview engine: one question at a time, always with a recommendation, exploring KB/codebase before asking. sync mode drives systematic AI-human alignment on every story aspect until explicit shared understanding is confirmed. Write-free by design — returns the synthesis to the caller, never writes adoption or issues. Invocable standalone or composed by /pair-process-brainstorm (phase 1, planned — #230) and /pair-process-refine-story (phase 0)." +description: "Interviews one question at a time, always with a recommendation, after exploring the KB/codebase first; sync mode drives systematic AI-human alignment on a story until shared understanding is confirmed. Invoke directly to interview on any topic ('grill me on the requirements'). Composed by /pair-process-refine-story and a future /pair-process-brainstorm (planned — #230). Write-free — returns the synthesis, never writes adoption or issues." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-manage-flags/SKILL.md b/.claude/skills/pair-capability-manage-flags/SKILL.md index 7e794889..5433e4a8 100644 --- a/.claude/skills/pair-capability-manage-flags/SKILL.md +++ b/.claude/skills/pair-capability-manage-flags/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-manage-flags -description: "Manages feature flag lifecycle: creation, activation, deactivation, and cleanup. Follows feature-flags guidelines. Idempotent: detects existing flags, shows current state, offers lifecycle actions rather than re-creating." +description: "Manages a feature flag's lifecycle — creation, activation, deactivation, cleanup — per the feature-flags guidelines. Invoke directly to create/retire a flag or check its current state; idempotent." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-map-contexts/SKILL.md b/.claude/skills/pair-capability-map-contexts/SKILL.md index 7f60e5a5..7cb10de5 100644 --- a/.claude/skills/pair-capability-map-contexts/SKILL.md +++ b/.claude/skills/pair-capability-map-contexts/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-map-contexts -description: "Maps subdomains to DDD bounded contexts, scoped to the caller's touched items. Assesses each relationship on integration strength, socio-technical distance and volatility to derive the integration pattern and gate unbalanced+volatile relationships at approval. Falls back to 'system areas' when no DDD artifacts exist yet. Produces/updates files in adoption/tech/boundedcontext/ using bounded-context-template.md. Composed by /pair-process-refine-story, /pair-process-plan-tasks, /brainstorm — full scope only via /pair-process-bootstrap. Idempotent." +description: "Maps subdomains to DDD bounded contexts and derives the integration pattern between them (integration strength, socio-technical distance, volatility), scoped to items just touched. Composed by /pair-process-refine-story, /pair-process-plan-tasks, a future /pair-process-brainstorm (planned — #230); full-scope re-mapping only via /pair-process-bootstrap." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-map-subdomains/SKILL.md b/.claude/skills/pair-capability-map-subdomains/SKILL.md index 3ce9c267..9c6f17e8 100644 --- a/.claude/skills/pair-capability-map-subdomains/SKILL.md +++ b/.claude/skills/pair-capability-map-subdomains/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-map-subdomains -description: "Classifies business capabilities into DDD subdomains (core/supporting/generic) with a Volatility rating, scoped to the caller's touched items. Falls back to 'system areas' when no DDD artifacts exist yet. Produces/updates files in adoption/product/subdomain/ using subdomain-template.md. Composed by /pair-process-refine-story, /pair-process-plan-initiatives, /pair-process-plan-epics, /brainstorm — full scope only via /pair-process-bootstrap. Idempotent." +description: "Classifies business capabilities into DDD subdomains (core, supporting, generic) with a volatility rating, scoped to items just touched. Composed by /pair-process-refine-story, /pair-process-plan-initiatives, /pair-process-plan-epics, a future /pair-process-brainstorm (planned — #230); full-scope re-mapping only via /pair-process-bootstrap." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-record-decision/SKILL.md b/.claude/skills/pair-capability-record-decision/SKILL.md index 706a7dd6..e42e73da 100644 --- a/.claude/skills/pair-capability-record-decision/SKILL.md +++ b/.claude/skills/pair-capability-record-decision/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-record-decision -description: "Records an architectural, non-architectural, or domain decision and is the SOLE writer of adoption files. Architectural decisions produce an ADR; non-architectural decisions produce an ADL entry; domain decisions meeting the 3-criteria gate produce a DDR and sync the context map. All always update the relevant adoption/context files. Accepts pre-rendered {content, target} from assess-* proposals (generic persister — no per-domain rendering). Invocable independently or composed by /pair-process-implement and /pair-process-review." +description: "Records a decision — ADR (architectural), ADL (non-architectural), or DDR (domain, 3-criteria gate) — and is the sole writer of adoption/context-map files. Invoke directly to record or backfill a decision already made ('write that down as an ADR'). Composed by /pair-process-implement and /pair-process-review." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-capability-setup-gates/SKILL.md b/.claude/skills/pair-capability-setup-gates/SKILL.md index 7c637c47..68c44463 100644 --- a/.claude/skills/pair-capability-setup-gates/SKILL.md +++ b/.claude/skills/pair-capability-setup-gates/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-setup-gates -description: "Configures CI/CD quality gates per quality-assurance guidelines, producing pipeline configuration for the adopted tech stack. Provisions shared lint/format config packages and husky pre-commit/pre-push hooks. Reads existing gate config from way-of-working. Idempotent: detects existing configuration, confirms rather than re-configuring." +description: "Configures CI/CD quality gates — pipeline config, shared lint/format packages, husky hooks — for the adopted tech stack. Invoke directly to set up or reconfigure gates; idempotent — confirms existing configuration rather than re-configuring." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-setup-pm/SKILL.md b/.claude/skills/pair-capability-setup-pm/SKILL.md index 00931df6..40b4343f 100644 --- a/.claude/skills/pair-capability-setup-pm/SKILL.md +++ b/.claude/skills/pair-capability-setup-pm/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-setup-pm -description: "Configures the project management tool by guiding selection from supported options, applying the implementation guide, updating way-of-working adoption, and recording the decision via /pair-capability-record-decision. Idempotent — detects existing configuration." +description: "Configures the project management tool — creates/wires it up, applies its implementation guide, updates way-of-working, records the decision — whether the tool was already chosen or picked here. Invoke directly to set up a tracker ('configure Jira', 'set up GitHub Projects'). Composed by /pair-process-bootstrap; /pair-capability-assess-pm delegates here once a tool is picked." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-verify-adoption/SKILL.md b/.claude/skills/pair-capability-verify-adoption/SKILL.md index 4c13cb90..03e55e7b 100644 --- a/.claude/skills/pair-capability-verify-adoption/SKILL.md +++ b/.claude/skills/pair-capability-verify-adoption/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-verify-adoption -description: "Checks code and configuration against project adoption files for a given scope. Detection-only: returns conformity/non-conformity list per area without resolving issues. Caller decides resolution. Invocable independently or composed by /pair-process-review and /pair-process-implement." +description: "Detects conformity/non-conformity of already-written code and configuration against the project's adopted decisions (architecture, tech-stack, infrastructure, etc.), for a given scope — a compliance audit, not a new-choice evaluation (that's /pair-capability-assess-stack and siblings). Detection-only; resolution is the caller's. Composed by /pair-process-review and /pair-process-implement; invoke directly to audit a scope on demand." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-verify-done/SKILL.md b/.claude/skills/pair-capability-verify-done/SKILL.md index f9cef2ae..34b4d79e 100644 --- a/.claude/skills/pair-capability-verify-done/SKILL.md +++ b/.claude/skills/pair-capability-verify-done/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-verify-done -description: "Checks Definition of Done criteria against a PR or work item. Reads universal DoD from quality-standards guidelines and project-specific criteria from adoption files. Already-passing criteria are skipped. Invocable independently or composed by /pair-process-review." +description: "Checks a PR or work item against Definition of Done criteria (universal + project-specific), skipping already-passing criteria. Composed by /pair-process-review; invoke directly to check DoD on demand ('is PR #42 actually done')." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-verify-quality/SKILL.md b/.claude/skills/pair-capability-verify-quality/SKILL.md index 699ff528..a0d19921 100644 --- a/.claude/skills/pair-capability-verify-quality/SKILL.md +++ b/.claude/skills/pair-capability-verify-quality/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-verify-quality -description: "Checks quality gates against the current codebase. Reads project-specific quality gate command from way-of-working adoption and universal standards from quality-standards guidelines. Gates already passing are skipped. Invocable independently or composed by /pair-process-implement and /pair-process-review." +description: "Checks whether the codebase currently passes its quality gates (lint, tests, type-check, coverage) — pass/fail per gate, skipping gates already passing. Composed by /pair-process-implement and /pair-process-review; invoke directly before pushing to check gates on demand." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-capability-write-issue/SKILL.md b/.claude/skills/pair-capability-write-issue/SKILL.md index 1a32f9c3..f98d6c08 100644 --- a/.claude/skills/pair-capability-write-issue/SKILL.md +++ b/.claude/skills/pair-capability-write-issue/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-write-issue -description: "Creates or updates issues in the adopted PM tool using template-driven formatting. Reads way-of-working for tool choice and type-specific templates for body structure. Supports topical labels (e.g. tech-debt) for deliberate promotion. Invocable independently or composed by /pair-process-refine-story, /pair-process-plan-tasks, /pair-process-plan-initiatives, /pair-process-plan-epics, and /pair-process-plan-stories." +description: "Creates or updates an issue in the adopted PM tool from a type-specific template (bug, story, epic, etc.), including topical labels (e.g. tech-debt) for deliberate promotion. Invoke directly to create/update one issue on demand. Composed by /pair-process-refine-story, /pair-process-plan-tasks, /pair-process-plan-initiatives, /pair-process-plan-epics, /pair-process-plan-stories." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-process-bootstrap/SKILL.md b/.claude/skills/pair-process-bootstrap/SKILL.md index 9b9dee6a..55108add 100644 --- a/.claude/skills/pair-process-bootstrap/SKILL.md +++ b/.claude/skills/pair-process-bootstrap/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-bootstrap -description: "Orchestrates full project setup: PRD verification, project categorization, checklist completion, standards generation, quality gate setup, and PM tool configuration. Composes /pair-process-specify-prd, /pair-capability-setup-pm, /pair-capability-record-decision, and assess-* (optional). Idempotent — detects completed phases and resumes." +description: "Orchestrates full project setup — PRD verification, project categorization, checklist, standards, quality gates, PM tool — for a brand-new project, end to end. Composes /pair-process-specify-prd, /pair-capability-setup-pm, /pair-capability-record-decision, assess-* (optional)." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-process-implement/SKILL.md b/.claude/skills/pair-process-implement/SKILL.md index 6719c3cc..5aeb2db8 100644 --- a/.claude/skills/pair-process-implement/SKILL.md +++ b/.claude/skills/pair-process-implement/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-implement -description: "Implements a user story by iterating through its tasks one at a time, following a structured 5-step cycle per task. Composes /pair-capability-verify-quality and /pair-capability-record-decision. Reads adoption files for project-specific decisions. Creates a PR at story completion." +description: "Implements a refined user story task-by-task, via a 5-step cycle per task (context, branch, implementation, quality, commit), and opens one PR when the story completes. Composes /pair-capability-verify-quality, /pair-capability-record-decision." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-process-plan-epics/SKILL.md b/.claude/skills/pair-process-plan-epics/SKILL.md index 868437d4..f38c1f32 100644 --- a/.claude/skills/pair-process-plan-epics/SKILL.md +++ b/.claude/skills/pair-process-plan-epics/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-plan-epics -description: "Breaks initiatives into epics through structured analysis and collaborative validation. Composes /pair-capability-write-issue with $type: epic. Idempotent: detects existing epics, creates only missing ones. Includes Epic 0 assessment for new projects." +description: "Breaks a strategic initiative into epics — each delivering end-to-end value in 2-4 sprints — through structured analysis and validation. Composes /pair-capability-write-issue. Not for filing a single epic issue from text you already wrote (that's /pair-capability-write-issue directly)." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-process-plan-initiatives/SKILL.md b/.claude/skills/pair-process-plan-initiatives/SKILL.md index 6f4054ec..fc5e5485 100644 --- a/.claude/skills/pair-process-plan-initiatives/SKILL.md +++ b/.claude/skills/pair-process-plan-initiatives/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-plan-initiatives -description: "Creates strategic initiatives from PRD analysis. Prioritizes by business impact (P0/P1/P2), composes /pair-capability-write-issue with $type: initiative. Idempotent: detects existing initiatives, creates only missing ones." +description: "Turns a PRD into prioritized (P0/P1/P2) strategic initiatives through structured analysis and validation. Composes /pair-capability-write-issue." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-process-plan-stories/SKILL.md b/.claude/skills/pair-process-plan-stories/SKILL.md index 202f72d9..e803ab2e 100644 --- a/.claude/skills/pair-process-plan-stories/SKILL.md +++ b/.claude/skills/pair-process-plan-stories/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-plan-stories -description: "Breaks epics into user stories using vertical slicing and INVEST validation. Composes /pair-capability-write-issue with $type: story. Idempotent: detects existing stories, creates only missing ones." +description: "Slices an epic into user stories via vertical slicing and INVEST validation, each sized for one sprint. Composes /pair-capability-write-issue." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-process-plan-tasks/SKILL.md b/.claude/skills/pair-process-plan-tasks/SKILL.md index 0a00c291..eb0f2886 100644 --- a/.claude/skills/pair-process-plan-tasks/SKILL.md +++ b/.claude/skills/pair-process-plan-tasks/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-plan-tasks -description: "Breaks a refined user story into implementation tasks. Task-level idempotency: detects existing tasks and creates only missing ones. Appends condensed Technical Analysis + Task Breakdown (checklist, Dependency Graph, AC Coverage table, detailed tasks) to the story body. Composes /pair-capability-write-issue to update the story issue body. Tasks are documented inline in the story — no separate task issues are created." +description: "Breaks a refined user story into implementation tasks — checklist, dependency graph, AC-coverage table — appended to the story body; no separate task issues are created. Composes /pair-capability-write-issue." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-process-refine-story/SKILL.md b/.claude/skills/pair-process-refine-story/SKILL.md index 8cd8b313..88848f35 100644 --- a/.claude/skills/pair-process-refine-story/SKILL.md +++ b/.claude/skills/pair-process-refine-story/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-refine-story -description: "Refines a user story from Todo to Refined state through structured phases: selection, requirements analysis (Given-When-Then), technical analysis, sprint readiness, and documentation. Section-level idempotency — detects partial refinement and resumes. Composes /pair-capability-write-issue for PM tool updates." +description: "Refines a user story from Todo to Refined — Given-When-Then acceptance criteria, technical analysis, sprint readiness. Composes /pair-capability-write-issue. Not for sizing an already-refined story (use /pair-capability-estimate)." version: 0.4.1 author: Foomakers --- diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 48159899..0aca98a1 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-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." +description: "Reviews a pull request through 6 sequential phases (5 review + optional merge with parent cascade) — validation, technical review, adoption compliance, completeness, decision — to decide whether it merges. Not a quick build/test sanity check (use /pair-capability-verify-quality). Composes /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 (optional)." version: 0.5.0 author: Foomakers --- diff --git a/.claude/skills/pair-process-specify-prd/SKILL.md b/.claude/skills/pair-process-specify-prd/SKILL.md index a064f37a..98cf847b 100644 --- a/.claude/skills/pair-process-specify-prd/SKILL.md +++ b/.claude/skills/pair-process-specify-prd/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-process-specify-prd -description: "Creates or updates a Product Requirements Document through structured template analysis, hypothesis-driven information gathering, and iterative review. Idempotent — detects existing PRD and offers selective section update." +description: "Creates or updates a Product Requirements Document through structured template analysis and iterative review — drafting a new PRD, or filling in a missing/outdated section." version: 0.4.1 author: Foomakers --- diff --git a/apps/website/content/docs/reference/skills-catalog.mdx b/apps/website/content/docs/reference/skills-catalog.mdx index 2b5253a1..e1e5eb00 100644 --- a/apps/website/content/docs/reference/skills-catalog.mdx +++ b/apps/website/content/docs/reference/skills-catalog.mdx @@ -19,15 +19,15 @@ Process skills orchestrate multi-step workflows by composing capability skills. | Skill | Command | Description | Composes | | ----- | ------- | ----------- | -------- | -| **specify-prd** | `/pair-process-specify-prd` | Creates or updates a Product Requirements Document through structured template analysis and iterative review. | — | -| **bootstrap** | `/pair-process-bootstrap` | Orchestrates full project setup: PRD verification, project categorization, checklist completion, standards generation, quality gate setup, and PM tool configuration. | `/pair-process-specify-prd`, `/pair-capability-setup-pm`, `/pair-capability-record-decision`, assess-* (optional) | -| **plan-initiatives** | `/pair-process-plan-initiatives` | Creates strategic initiatives from PRD analysis. Prioritizes by business impact (P0/P1/P2). | `/pair-capability-write-issue` | -| **plan-epics** | `/pair-process-plan-epics` | Breaks initiatives into epics through structured analysis and collaborative validation. Includes Epic 0 assessment. | `/pair-capability-write-issue` | -| **plan-stories** | `/pair-process-plan-stories` | Breaks epics into user stories using vertical slicing and INVEST validation. | `/pair-capability-write-issue` | -| **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-analyze-debt` (required); `/pair-capability-verify-adoption`, `/pair-capability-assess-stack`, `/pair-capability-execute-manual-tests` (optional) | +| **specify-prd** | `/pair-process-specify-prd` | Creates or updates a Product Requirements Document through structured template analysis and iterative review — drafting a new PRD, or filling in a missing/outdated section. | — | +| **bootstrap** | `/pair-process-bootstrap` | Orchestrates full project setup — PRD verification, categorization, checklist, standards, quality gates, PM tool — for a brand-new project, end to end. | `/pair-process-specify-prd`, `/pair-capability-setup-pm`, `/pair-capability-record-decision`, assess-* (optional) | +| **plan-initiatives** | `/pair-process-plan-initiatives` | Turns a PRD into prioritized (P0/P1/P2) strategic initiatives through structured analysis and validation. | `/pair-capability-write-issue` | +| **plan-epics** | `/pair-process-plan-epics` | Breaks a strategic initiative into epics — each delivering end-to-end value in 2-4 sprints. Not for filing a single epic issue from text you already wrote (that's write-issue directly). | `/pair-capability-write-issue` | +| **plan-stories** | `/pair-process-plan-stories` | Slices an epic into user stories via vertical slicing and INVEST validation, each sized for one sprint. | `/pair-capability-write-issue` | +| **refine-story** | `/pair-process-refine-story` | Refines a user story from Todo to Refined — Given-When-Then acceptance criteria, technical analysis, sprint readiness. Not for sizing an already-refined story (use estimate). | `/pair-capability-write-issue` | +| **plan-tasks** | `/pair-process-plan-tasks` | Breaks a refined user story into implementation tasks — checklist, dependency graph, AC-coverage table — appended to the story body; no separate task issues. | `/pair-capability-write-issue` | +| **implement** | `/pair-process-implement` | Implements a refined user story task-by-task via a 5-step cycle per task (context, branch, implementation, quality, commit); opens one PR when the story completes. | `/pair-capability-verify-quality`, `/pair-capability-record-decision` | +| **review** | `/pair-process-review` | Reviews a pull request through 6 sequential phases (5 review + optional merge with parent cascade) to decide whether it merges. Not a quick build/test sanity check (use verify-quality). | `/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 @@ -37,8 +37,8 @@ Capability skills are atomic operations invoked independently or composed by pro | Skill | Command | Description | | ----- | ------- | ----------- | -| **map-subdomains** | `/pair-capability-map-subdomains` | Classifies business capabilities into DDD subdomains (core/supporting/generic) with a Volatility rating, scoped to the caller's touched items. Falls back to "system areas" when no DDD artifacts exist. Composed by `/pair-process-refine-story`, `/pair-process-plan-initiatives`, `/pair-process-plan-epics`; full scope only via `/pair-process-bootstrap`. | -| **map-contexts** | `/pair-capability-map-contexts` | Maps subdomains to DDD bounded contexts, scoped to the caller's touched items. Assesses each relationship on integration strength, socio-technical distance and volatility; gates unbalanced+volatile relationships at approval. Composed by `/pair-process-refine-story`, `/pair-process-plan-tasks`; full scope only via `/pair-process-bootstrap`. | +| **map-subdomains** | `/pair-capability-map-subdomains` | Classifies business capabilities into DDD subdomains (core, supporting, generic) with a volatility rating, scoped to items just touched. Composed by `/pair-process-refine-story`, `/pair-process-plan-initiatives`, `/pair-process-plan-epics`; full-scope re-mapping only via `/pair-process-bootstrap`. | +| **map-contexts** | `/pair-capability-map-contexts` | Maps subdomains to DDD bounded contexts and derives the integration pattern between them (integration strength, socio-technical distance, volatility), scoped to items just touched. Composed by `/pair-process-refine-story`, `/pair-process-plan-tasks`; full-scope re-mapping only via `/pair-process-bootstrap`. | Reclassified from process skills — see [Migration Notes](/docs/reference/skill-management#migration-notes). @@ -48,14 +48,14 @@ All `assess-*` skills are **output-only**: they produce a proposal (rendered ado | Skill | Command | Description | | ----- | ------- | ----------- | -| **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-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`. | -| **assess-pm** | `/pair-capability-assess-pm` | Assess project management tool choice. Output-only — proposes PM-section content; persists via `/pair-capability-setup-pm` or the caller's `/pair-capability-record-decision`. | -| **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`. | +| **assess-ai** | `/pair-capability-assess-ai` | Evaluates and recommends AI development tools — coding assistants, agent frameworks, MCP integrations, models — when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | +| **assess-architecture** | `/pair-capability-assess-architecture` | Evaluates and recommends an architecture pattern (layered, hexagonal, microservices, etc.) when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | +| **assess-infrastructure** | `/pair-capability-assess-infrastructure` | Evaluates and recommends infrastructure strategy — cloud, CI/CD, deployment, IaC, environments — when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | +| **assess-methodology** | `/pair-capability-assess-methodology` | Evaluates and recommends the development methodology (Scrum, Kanban, Lean, etc.) — iterations, ceremonies, flow — when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | +| **assess-observability** | `/pair-capability-assess-observability` | Evaluates and recommends the observability strategy — monitoring, logging, tracing, alerting, telemetry — when the choice is open. Output-only; caller persists via `/pair-capability-record-decision`. | +| **assess-pm** | `/pair-capability-assess-pm` | Evaluates and recommends which PM tool fits, when the choice is still open — proposes, doesn't configure. `/pair-capability-setup-pm` configures the tool once picked; otherwise the caller persists via `/pair-capability-record-decision`. | +| **assess-stack** | `/pair-capability-assess-stack` | Evaluates and recommends the tech stack when the choice is open: full evaluation at bootstrap, or a single new dependency during implementation. Doesn't audit code already written (that's verify-adoption). Output-only; caller persists via `/pair-capability-record-decision`. | +| **assess-testing** | `/pair-capability-assess-testing` | Evaluates and recommends the testing strategy — framework, pyramid distribution, coverage targets — when the choice is open. Doesn't write tests itself. Output-only; caller persists via `/pair-capability-record-decision`. | ### Analysis Capabilities @@ -63,51 +63,51 @@ All `analyze-*` skills are **output-only report producers**: they analyze and re | 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. | +| **analyze-code-quality** | `/pair-capability-analyze-code-quality` | Produces an objective code quality report (complexity, size, coverage, duplication, maintainability). Composed by `/pair-process-review`; invoke directly for a report on demand. Output-only, never blocks. | +| **analyze-debt** | `/pair-capability-analyze-debt` | Produces a technical debt report (code, design, test, documentation, infrastructure), prioritized by impact x effort. Composed by `/pair-process-review`; invoke directly to catalog debt. Output-only, never blocks a PR. | ### Verification Capabilities | Skill | Command | Description | | ----- | ------- | ----------- | -| **verify-adoption** | `/pair-capability-verify-adoption` | Checks code against adoption files for a given scope. Detection-only: returns conformity/non-conformity list. | -| **verify-done** | `/pair-capability-verify-done` | Checks Definition of Done criteria against a PR or work item. | -| **verify-quality** | `/pair-capability-verify-quality` | Checks quality gates against the current codebase. | +| **verify-adoption** | `/pair-capability-verify-adoption` | Detects conformity/non-conformity of already-written code against the project's adopted decisions, for a given scope — a compliance audit, not a new-choice evaluation (that's assess-stack and siblings). Detection-only. | +| **verify-done** | `/pair-capability-verify-done` | Checks a PR or work item against Definition of Done criteria, skipping already-passing criteria. Composed by `/pair-process-review`; invoke directly on demand. | +| **verify-quality** | `/pair-capability-verify-quality` | Checks whether the codebase currently passes its quality gates (lint, tests, type-check, coverage), skipping gates already passing. Composed by `/pair-process-implement`, `/pair-process-review`. | ### Setup and Management Capabilities | Skill | Command | Description | | ----- | ------- | ----------- | -| **setup-pm** | `/pair-capability-setup-pm` | Configures the project management tool: selection, implementation guide, adoption update. | -| **setup-gates** | `/pair-capability-setup-gates` | Configures CI/CD quality gates per quality-assurance guidelines. | -| **manage-flags** | `/pair-capability-manage-flags` | Manages feature flag lifecycle: creation, activation, deactivation, cleanup. | +| **setup-pm** | `/pair-capability-setup-pm` | Configures the PM tool — creates/wires it up, applies its implementation guide, updates way-of-working — whether already chosen or picked here. Composed by `/pair-process-bootstrap`; delegated to by assess-pm. | +| **setup-gates** | `/pair-capability-setup-gates` | Configures CI/CD quality gates — pipeline config, lint/format packages, husky hooks — for the adopted tech stack. Idempotent. | +| **manage-flags** | `/pair-capability-manage-flags` | Manages a feature flag's lifecycle: creation, activation, deactivation, cleanup. | ### Quality Assurance Capabilities | Skill | Command | Description | | ----- | ------- | ----------- | -| **design-manual-tests** | `/pair-capability-design-manual-tests` | Designs a manual test suite by analyzing the project's artifacts, architecture, and deployment targets. Generates critical path files and a suite README. | -| **execute-manual-tests** | `/pair-capability-execute-manual-tests` | Executes a project's manual test suite against released artifacts, producing a structured report with PASS/FAIL per test case. If no suite exists, halts with guidance to run `/pair-capability-design-manual-tests` first. | +| **design-manual-tests** | `/pair-capability-design-manual-tests` | Designs a manual test suite — critical path files + suite README — for post-release validation. Not for planning the automated-testing approach (use assess-testing). | +| **execute-manual-tests** | `/pair-capability-execute-manual-tests` | Executes a project's manual test suite against released/deployed artifacts, producing a structured PASS/FAIL report per critical path. Not for running the automated suite (use verify-quality). If no suite exists, halts with guidance to run `/pair-capability-design-manual-tests` first. | ### Recording and Writing Capabilities | Skill | Command | Description | | ----- | ------- | ----------- | -| **record-decision** | `/pair-capability-record-decision` | Records an architectural (ADR), non-architectural (ADL), or domain (DDR) decision. The **sole writer** of adoption files: accepts pre-rendered `{content, target}` from assess-* proposals (generic persist) and updates adoption files or syncs the context map. | -| **write-issue** | `/pair-capability-write-issue` | Creates or updates issues in the adopted PM tool using template-driven formatting. Supports topical labels (e.g. `tech-debt`) for deliberate backlog promotion. | -| **estimate** | `/pair-capability-estimate` | Estimates a refined user story using the adopted estimation methodology. | +| **record-decision** | `/pair-capability-record-decision` | Records a decision — ADR (architectural), ADL (non-architectural), or DDR (domain) — and is the **sole writer** of adoption/context-map files. Invoke directly to record or backfill a decision already made. Composed by `/pair-process-implement`, `/pair-process-review`. | +| **write-issue** | `/pair-capability-write-issue` | Creates or updates an issue in the adopted PM tool from a type-specific template. Supports topical labels (e.g. `tech-debt`) for deliberate backlog promotion. | +| **estimate** | `/pair-capability-estimate` | Estimates story points for a refined user story using the adopted estimation methodology; confirms rather than re-estimating if already sized. | ### Discovery Capabilities | Skill | Command | Description | | ----- | ------- | ----------- | -| **grill** | `/pair-capability-grill` | Reusable interview engine: one question at a time, always with a recommendation, exploring KB/codebase before asking. `sync` mode drives systematic AI-human alignment on a story until explicit shared understanding. Write-free — returns the synthesis to the caller. | +| **grill** | `/pair-capability-grill` | Interviews one question at a time, always with a recommendation, after exploring the KB/codebase first; `sync` mode drives systematic AI-human alignment on a story until shared understanding. Invoke directly to interview on any topic. Write-free — returns the synthesis to the caller. | ### State and Handoff Capabilities | Skill | Command | Description | | ----- | ------- | ----------- | -| **checkpoint** | `/pair-capability-checkpoint` | Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) in `.pair/working/checkpoints/`, so work survives context resets. | +| **checkpoint** | `/pair-capability-checkpoint` | Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) in `.pair/working/checkpoints/`, so work survives a context reset. Invoke directly to save or resume progress. | ## Skill Properties 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 967e0953..386f3447 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 @@ -1,6 +1,6 @@ --- 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." +description: "Produces an objective code quality report — complexity, size, coverage, duplication, maintainability score — for a repo or package, with actionable recommendations. Composed by /review; invoke directly for a report on demand ('code quality report', 'how maintainable is this'). Output-only: writes nothing, never blocks." version: 0.5.0 author: Foomakers --- 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 b435abee..c901c8a8 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/analyze-debt/SKILL.md @@ -1,6 +1,6 @@ --- 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." +description: "Produces a technical debt report — categorized items (code, design, test, documentation, infrastructure), prioritized by impact x effort. Composed by /review; invoke directly to catalog and prioritize debt on demand. Output-only: writes no files, creates no backlog items, never blocks a PR." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md index dcc37f65..7281b5d1 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-ai/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-ai -description: "Assess AI development tools using resolution cascade (Argument > Adoption > Assessment). Reads AI development guidelines, proposes AI tool choices with versions and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /record-decision. Idempotent." +description: "Evaluates and recommends AI development tools — coding assistants (Copilot, Claude Code, Cursor), agent frameworks, MCP integrations, models — when the choice is open. Output-only: emits a proposal + target for /record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md index 5955aaf9..8210f2ba 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-architecture/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-architecture -description: "Assess architecture pattern using resolution cascade (Argument > Adoption > Assessment). Reads architecture guidelines, proposes a pattern and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /record-decision. Idempotent." +description: "Evaluates and recommends an architecture pattern (layered, hexagonal, microservices, modular monolith, etc.) when the choice is open. Output-only: emits a proposal + target for /record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md index 169847ab..feafbdf2 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-infrastructure/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-infrastructure -description: "Assess infrastructure strategy using resolution cascade (Argument > Adoption > Assessment). Reads infrastructure guidelines, proposes cloud/CI/CD/deployment choices and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /record-decision. Idempotent." +description: "Evaluates and recommends infrastructure strategy — cloud provider, CI/CD pipeline, deployment pattern, IaC, environments — when the choice is open. Output-only: emits a proposal + target for /record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md index 48bbfd8c..9b7704b6 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-methodology/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-methodology -description: "Assess development methodology using resolution cascade (Argument > Adoption > Assessment). Reads methodology guidelines, proposes Scrum/Kanban/Lean/etc. and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /record-decision. Idempotent." +description: "Evaluates and recommends the development methodology (Scrum, Kanban, Lean, SAFe, hybrid) — iterations, ceremonies, flow — when the choice is open. Output-only: emits a proposal + target for /record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md index 1d8438b5..2ad8e6e4 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-observability/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-observability -description: "Assess observability strategy using resolution cascade (Argument > Adoption > Assessment). Reads observability guidelines, proposes monitoring/logging/tracing choices and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /record-decision. Idempotent." +description: "Evaluates and recommends the observability strategy — monitoring, logging, tracing, alerting, telemetry — when the choice is open. Output-only: emits a proposal + target for /record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md index 1bf73ea4..d22d6d72 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-pm/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-pm -description: "Assess project management tool using resolution cascade (Argument > Adoption > Assessment). Reads PM tool guidelines, proposes a tool choice and emits rendered adoption content + target (output-only, writes nothing); persistence via /setup-pm or the caller's /record-decision. Idempotent." +description: "Evaluates and recommends which project management tool fits this project (Jira, Linear, GitHub Projects, etc.) when the choice is still open — proposes a choice, doesn't configure anything. /setup-pm configures the tool once picked; otherwise the caller persists the proposal via /record-decision." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md index 83402c85..7a714283 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-stack -description: "Assess tech stack using resolution cascade (Argument > Adoption > Assessment). Lifecycle-spanning: bootstrap (full eval), implementation (add dependency), review (detect unlisted). Version tracking. Output-only: emits rendered adoption content + target; the caller persists via /record-decision. Idempotent." +description: "Evaluates and recommends the tech stack — languages, frameworks, database, libraries, versions — when the choice is open: full evaluation at bootstrap, or a single new dependency during implementation ('should we add Redis', 'is this new dependency consistent with our stack'). Doesn't audit code already written (that's /verify-adoption). Output-only: emits a proposal + target for /record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md index bb2a49b1..97819f9b 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-testing -description: "Assess testing strategy using resolution cascade (Argument > Adoption > Assessment). Reads testing guidelines, proposes framework and strategy and emits rendered adoption content + target (output-only, writes nothing); the caller persists via /record-decision. Idempotent." +description: "Evaluates and recommends the testing strategy — framework, pyramid distribution, coverage targets, TDD approach — when the choice is open. Doesn't write tests itself. Output-only: emits a proposal + target for /record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md index 2d5f031c..1d900373 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md @@ -1,6 +1,6 @@ --- name: checkpoint -description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives context resets. Write mode persists state to .pair/working/checkpoints/.md, one file per story; resume mode locates and parses it. Invocable independently; composed by a future closing phase of /implement and a future /publish-pr (planned — #255) as a handoff." +description: "Writes and resumes a self-contained progress checkpoint (story, branch, tasks done, decisions, remaining todos) so work survives a context reset. Invoke directly to save or resume progress ('save our progress on #313', 'resume story #256'); composed by a future closing phase of /implement and a future /publish-pr (planned — #255)." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md index b81c7cc4..7e4004d9 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md @@ -1,6 +1,6 @@ --- name: design-manual-tests -description: "Designs a manual test suite for post-release validation by analyzing the project's artifacts, architecture, and deployment targets. Generates critical path files (CP*.md) and a suite README following manual-testing guidelines and the manual-test-case-template. Invocable independently or as a prerequisite of /execute-manual-tests." +description: "Designs a manual test suite — critical path files + suite README — for post-release validation, by analyzing released artifacts, architecture, and deployment targets. Not for planning the automated-testing approach (use /assess-testing). Prerequisite for /execute-manual-tests." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/estimate/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/estimate/SKILL.md index bf44d6ca..4e255934 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/estimate/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/estimate/SKILL.md @@ -1,6 +1,6 @@ --- name: estimate -description: "Estimates a refined user story using the adopted estimation methodology. Reads estimation framework from guidelines and methodology from way-of-working. Idempotent: detects existing estimate, confirms rather than re-estimating. Invocable independently or composed by /refine-story." +description: "Estimates story points for a refined user story using the project's adopted estimation methodology; confirms rather than re-estimating if already sized. Composed by /refine-story; invoke directly to size a story on demand ('estimate story #87')." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/execute-manual-tests/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/execute-manual-tests/SKILL.md index 9469797d..30d01b1e 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/execute-manual-tests/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/execute-manual-tests/SKILL.md @@ -1,6 +1,6 @@ --- name: execute-manual-tests -description: "Executes a project's manual test suite against released artifacts, producing a structured report. Resolves test variables, iterates through critical paths, records PASS/FAIL per test case, and generates the report from the manual-test-report template. Invocable independently or composed by /review (post-merge validation)." +description: "Executes a project's manual test suite against released or deployed artifacts, producing a structured PASS/FAIL report per critical path. Not for running the automated test suite (use /verify-quality). Composed by /review for post-merge validation." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md index c7de7b14..f0f7cba8 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md @@ -1,6 +1,6 @@ --- name: grill -description: "Reusable interview engine: one question at a time, always with a recommendation, exploring KB/codebase before asking. sync mode drives systematic AI-human alignment on every story aspect until explicit shared understanding is confirmed. Write-free by design — returns the synthesis to the caller, never writes adoption or issues. Invocable standalone or composed by /brainstorm (phase 1, planned — #230) and /refine-story (phase 0)." +description: "Interviews one question at a time, always with a recommendation, after exploring the KB/codebase first; sync mode drives systematic AI-human alignment on a story until shared understanding is confirmed. Invoke directly to interview on any topic ('grill me on the requirements'). Composed by /refine-story and a future /brainstorm (planned — #230). Write-free — returns the synthesis, never writes adoption or issues." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/manage-flags/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/manage-flags/SKILL.md index 918a507c..7df7296e 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/manage-flags/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/manage-flags/SKILL.md @@ -1,6 +1,6 @@ --- name: manage-flags -description: "Manages feature flag lifecycle: creation, activation, deactivation, and cleanup. Follows feature-flags guidelines. Idempotent: detects existing flags, shows current state, offers lifecycle actions rather than re-creating." +description: "Manages a feature flag's lifecycle — creation, activation, deactivation, cleanup — per the feature-flags guidelines. Invoke directly to create/retire a flag or check its current state; idempotent." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md index b3f46bab..6e857db4 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/map-contexts/SKILL.md @@ -1,6 +1,6 @@ --- name: map-contexts -description: "Maps subdomains to DDD bounded contexts, scoped to the caller's touched items. Assesses each relationship on integration strength, socio-technical distance and volatility to derive the integration pattern and gate unbalanced+volatile relationships at approval. Falls back to 'system areas' when no DDD artifacts exist yet. Produces/updates files in adoption/tech/boundedcontext/ using bounded-context-template.md. Composed by /refine-story, /plan-tasks, /brainstorm — full scope only via /bootstrap. Idempotent." +description: "Maps subdomains to DDD bounded contexts and derives the integration pattern between them (integration strength, socio-technical distance, volatility), scoped to items just touched. Composed by /refine-story, /plan-tasks, a future /brainstorm (planned — #230); full-scope re-mapping only via /bootstrap." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md index 3c3ddb59..1cb6e56e 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/map-subdomains/SKILL.md @@ -1,6 +1,6 @@ --- name: map-subdomains -description: "Classifies business capabilities into DDD subdomains (core/supporting/generic) with a Volatility rating, scoped to the caller's touched items. Falls back to 'system areas' when no DDD artifacts exist yet. Produces/updates files in adoption/product/subdomain/ using subdomain-template.md. Composed by /refine-story, /plan-initiatives, /plan-epics, /brainstorm — full scope only via /bootstrap. Idempotent." +description: "Classifies business capabilities into DDD subdomains (core, supporting, generic) with a volatility rating, scoped to items just touched. Composed by /refine-story, /plan-initiatives, /plan-epics, a future /brainstorm (planned — #230); full-scope re-mapping only via /bootstrap." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md index 1841fad4..d741a86f 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/record-decision/SKILL.md @@ -1,6 +1,6 @@ --- name: record-decision -description: "Records an architectural, non-architectural, or domain decision and is the SOLE writer of adoption files. Architectural decisions produce an ADR; non-architectural decisions produce an ADL entry; domain decisions meeting the 3-criteria gate produce a DDR and sync the context map. All always update the relevant adoption/context files. Accepts pre-rendered {content, target} from assess-* proposals (generic persister — no per-domain rendering). Invocable independently or composed by /implement and /review." +description: "Records a decision — ADR (architectural), ADL (non-architectural), or DDR (domain, 3-criteria gate) — and is the sole writer of adoption/context-map files. Invoke directly to record or backfill a decision already made ('write that down as an ADR'). Composed by /implement and /review." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md index b9e8dd04..87a7a44e 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/setup-gates/SKILL.md @@ -1,6 +1,6 @@ --- name: setup-gates -description: "Configures CI/CD quality gates per quality-assurance guidelines, producing pipeline configuration for the adopted tech stack. Provisions shared lint/format config packages and husky pre-commit/pre-push hooks. Reads existing gate config from way-of-working. Idempotent: detects existing configuration, confirms rather than re-configuring." +description: "Configures CI/CD quality gates — pipeline config, shared lint/format packages, husky hooks — for the adopted tech stack. Invoke directly to set up or reconfigure gates; idempotent — confirms existing configuration rather than re-configuring." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md index 00783215..cfc4d528 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/setup-pm/SKILL.md @@ -1,6 +1,6 @@ --- name: setup-pm -description: "Configures the project management tool by guiding selection from supported options, applying the implementation guide, updating way-of-working adoption, and recording the decision via /record-decision. Idempotent — detects existing configuration." +description: "Configures the project management tool — creates/wires it up, applies its implementation guide, updates way-of-working, records the decision — whether the tool was already chosen or picked here. Invoke directly to set up a tracker ('configure Jira', 'set up GitHub Projects'). Composed by /bootstrap; /assess-pm delegates here once a tool is picked." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md index 82456428..47ccd9c9 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-adoption/SKILL.md @@ -1,6 +1,6 @@ --- name: verify-adoption -description: "Checks code and configuration against project adoption files for a given scope. Detection-only: returns conformity/non-conformity list per area without resolving issues. Caller decides resolution. Invocable independently or composed by /review and /implement." +description: "Detects conformity/non-conformity of already-written code and configuration against the project's adopted decisions (architecture, tech-stack, infrastructure, etc.), for a given scope — a compliance audit, not a new-choice evaluation (that's /assess-stack and siblings). Detection-only; resolution is the caller's. Composed by /review and /implement; invoke directly to audit a scope on demand." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md index 63d0740d..f0c8ae54 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-done/SKILL.md @@ -1,6 +1,6 @@ --- name: verify-done -description: "Checks Definition of Done criteria against a PR or work item. Reads universal DoD from quality-standards guidelines and project-specific criteria from adoption files. Already-passing criteria are skipped. Invocable independently or composed by /review." +description: "Checks a PR or work item against Definition of Done criteria (universal + project-specific), skipping already-passing criteria. Composed by /review; invoke directly to check DoD on demand ('is PR #42 actually done')." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md index 47ccc7c4..3aa8dd25 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md @@ -1,6 +1,6 @@ --- name: verify-quality -description: "Checks quality gates against the current codebase. Reads project-specific quality gate command from way-of-working adoption and universal standards from quality-standards guidelines. Gates already passing are skipped. Invocable independently or composed by /implement and /review." +description: "Checks whether the codebase currently passes its quality gates (lint, tests, type-check, coverage) — pass/fail per gate, skipping gates already passing. Composed by /implement and /review; invoke directly before pushing to check gates on demand." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md index c6bb8d3d..32c29877 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/write-issue/SKILL.md @@ -1,6 +1,6 @@ --- name: write-issue -description: "Creates or updates issues in the adopted PM tool using template-driven formatting. Reads way-of-working for tool choice and type-specific templates for body structure. Supports topical labels (e.g. tech-debt) for deliberate promotion. Invocable independently or composed by /refine-story, /plan-tasks, /plan-initiatives, /plan-epics, and /plan-stories." +description: "Creates or updates an issue in the adopted PM tool from a type-specific template (bug, story, epic, etc.), including topical labels (e.g. tech-debt) for deliberate promotion. Invoke directly to create/update one issue on demand. Composed by /refine-story, /plan-tasks, /plan-initiatives, /plan-epics, /plan-stories." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md index 7f0b8891..41ce62db 100644 --- a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md @@ -1,6 +1,6 @@ --- name: bootstrap -description: "Orchestrates full project setup: PRD verification, project categorization, checklist completion, standards generation, quality gate setup, and PM tool configuration. Composes /specify-prd, /setup-pm, /record-decision, and assess-* (optional). Idempotent — detects completed phases and resumes." +description: "Orchestrates full project setup — PRD verification, project categorization, checklist, standards, quality gates, PM tool — for a brand-new project, end to end. Composes /specify-prd, /setup-pm, /record-decision, assess-* (optional)." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md index 18677343..56737581 100644 --- a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md @@ -1,6 +1,6 @@ --- name: implement -description: "Implements a user story by iterating through its tasks one at a time, following a structured 5-step cycle per task. Composes /verify-quality and /record-decision. Reads adoption files for project-specific decisions. Creates a PR at story completion." +description: "Implements a refined user story task-by-task, via a 5-step cycle per task (context, branch, implementation, quality, commit), and opens one PR when the story completes. Composes /verify-quality, /record-decision." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md index a6462305..9e314343 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-epics/SKILL.md @@ -1,6 +1,6 @@ --- name: plan-epics -description: "Breaks initiatives into epics through structured analysis and collaborative validation. Composes /write-issue with $type: epic. Idempotent: detects existing epics, creates only missing ones. Includes Epic 0 assessment for new projects." +description: "Breaks a strategic initiative into epics — each delivering end-to-end value in 2-4 sprints — through structured analysis and validation. Composes /write-issue. Not for filing a single epic issue from text you already wrote (that's /write-issue directly)." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md index f26019f1..3a225d60 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-initiatives/SKILL.md @@ -1,6 +1,6 @@ --- name: plan-initiatives -description: "Creates strategic initiatives from PRD analysis. Prioritizes by business impact (P0/P1/P2), composes /write-issue with $type: initiative. Idempotent: detects existing initiatives, creates only missing ones." +description: "Turns a PRD into prioritized (P0/P1/P2) strategic initiatives through structured analysis and validation. Composes /write-issue." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md index e552fbe7..1566d186 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-stories/SKILL.md @@ -1,6 +1,6 @@ --- name: plan-stories -description: "Breaks epics into user stories using vertical slicing and INVEST validation. Composes /write-issue with $type: story. Idempotent: detects existing stories, creates only missing ones." +description: "Slices an epic into user stories via vertical slicing and INVEST validation, each sized for one sprint. Composes /write-issue." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md index 63702d16..f45776b7 100644 --- a/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/plan-tasks/SKILL.md @@ -1,6 +1,6 @@ --- name: plan-tasks -description: "Breaks a refined user story into implementation tasks. Task-level idempotency: detects existing tasks and creates only missing ones. Appends condensed Technical Analysis + Task Breakdown (checklist, Dependency Graph, AC Coverage table, detailed tasks) to the story body. Composes /write-issue to update the story issue body. Tasks are documented inline in the story — no separate task issues are created." +description: "Breaks a refined user story into implementation tasks — checklist, dependency graph, AC-coverage table — appended to the story body; no separate task issues are created. Composes /write-issue." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md index 0f2e00e0..a18bf1e9 100644 --- a/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md @@ -1,6 +1,6 @@ --- name: refine-story -description: "Refines a user story from Todo to Refined state through structured phases: selection, requirements analysis (Given-When-Then), technical analysis, sprint readiness, and documentation. Section-level idempotency — detects partial refinement and resumes. Composes /write-issue for PM tool updates." +description: "Refines a user story from Todo to Refined — Given-When-Then acceptance criteria, technical analysis, sprint readiness. Composes /write-issue. Not for sizing an already-refined story (use /estimate)." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index 0ed0a177..1c98f5e2 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, /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." +description: "Reviews a pull request through 6 sequential phases (5 review + optional merge with parent cascade) — validation, technical review, adoption compliance, completeness, decision — to decide whether it merges. Not a quick build/test sanity check (use /verify-quality). Composes /verify-quality, /verify-done, /record-decision, /analyze-debt (required), /verify-adoption, /assess-stack (optional)." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md index 5acfb5d9..c82a1acc 100644 --- a/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/specify-prd/SKILL.md @@ -1,6 +1,6 @@ --- name: specify-prd -description: "Creates or updates a Product Requirements Document through structured template analysis, hypothesis-driven information gathering, and iterative review. Idempotent — detects existing PRD and offers selective section update." +description: "Creates or updates a Product Requirements Document through structured template analysis and iterative review — drafting a new PRD, or filling in a missing/outdated section." version: 0.4.1 author: Foomakers --- diff --git a/packages/knowledge-hub/eval/results/2026-07-13-after-t3.md b/packages/knowledge-hub/eval/results/2026-07-13-after-t3.md new file mode 100644 index 00000000..9443ce20 --- /dev/null +++ b/packages/knowledge-hub/eval/results/2026-07-13-after-t3.md @@ -0,0 +1,274 @@ +# Trigger Eval — After T3 (2026-07-13) + +Run of `../trigger-prompts.json` against the **rewritten** frontmatter descriptions (T3 of +story #313 — trigger-oriented rewrite of all 35 `description` fields). This is the "after" half +of the before/after evidence required by AC7 and by principle 9 ("Evaluation") of the authoring +standard. Baseline ("before"): `2026-07-12-baseline.md`. + +## Methodology + +- **Executor**: single LLM (Claude, Sonnet 5), single pass per prompt. The executor was shown the + full catalog of 35 `name` + `description` pairs (frontmatter only, post-T3) and one prompt at a + time, cold (no conversation history about the corpus beyond having authored the rewrite in the + same session — see bias disclosure below). +- **Instruction**: pick the single skill you would load, `none` if no skill applies, name all + candidates when two or more descriptions claim the prompt equally. +- **Bias disclosure**: same caveat as the baseline — the description author and the eval executor + are the same model/session lineage, and here the rewrite was explicitly targeted at the three + known ambiguities (AD-12, AD-14, PB-N2). Ambiguity may be *under*-reported for that reason. To + compensate, every prompt (not just the previously-ambiguous ones) was re-run against the full + new catalog rather than only re-checking the three known cases, so a regression on an + unrelated, previously-clean prompt would still surface. Near-ties resolved by judgment are + marked PASS with a note rather than silently passed, exactly as in the baseline. +- **Verdicts**: PASS (selected = expected), AMBIGUOUS (>=2 candidates named), FAIL (selected != + expected). +- **Scope note**: `next`'s description was reviewed and left unchanged — it already satisfied + principle 1 (when-to-use phrasing, no body-identity restatement) per the baseline's own + observation that it was the one description already conformant. All other 34 descriptions were + rewritten. + +## Summary + +| Type | Prompts | PASS | AMBIGUOUS | FAIL | Strict pass rate | +| ---- | ------- | ---- | --------- | ---- | ---------------- | +| should-trigger | 53 | 53 | 0 | 0 | 100% | +| should-not-trigger | 26 | 26 | 0 | 0 | 100% | +| **Total** | **79** | **79** | **0** | **0** | **100%** | + +Baseline was 76/79 (96.2%), 3 AMBIGUOUS, 0 FAIL. After T3: 79/79 (100%), 0 AMBIGUOUS, 0 FAIL — no +regression on any of the 76 previously-passing prompts, and all 3 previously-ambiguous prompts now +resolve cleanly. + +## Before -> After per family + +| Family | Before pass rate | After pass rate | Delta | Notes | +| ------ | ----------------- | ---------------- | ----- | ----- | +| router | 3/3 (100%) | 3/3 (100%) | — | unchanged (next untouched) | +| assess-decision | 18/20 (90%, 2 AMBIGUOUS: AD-12, AD-14) | 20/20 (100%) | +2 | both ambiguities resolved (see below); AD-02/08/10 upgraded from judgment-call PASS to verbatim-keyword PASS | +| analyze-report (was assess-report) | 6/6 (100%) | 6/6 (100%) | — | already clean pre-T3 (T8 rename); T3 tightened wording, no change in outcome | +| verification | 6/6 (100%) | 6/6 (100%) | — | unchanged outcome; VF-02/VF-03 upgraded to verbatim-keyword PASS | +| decision-recording | 3/3 (100%) | 3/3 (100%) | — | unchanged outcome; AD-N2 defusal made explicit ("already made" vs "choice is open") | +| pm-and-backlog | 5/6 (83%, 1 AMBIGUOUS: PB-N2) | 6/6 (100%) | +1 | PB-N2 resolved (same root cause as AD-12); PB-03/PB-04 upgraded to verbatim-keyword PASS | +| ddd-mapping | 4/4 (100%) | 4/4 (100%) | — | unchanged outcome; DM-N2's felt pull reduced (description no longer contains the bare word "domain") | +| session-continuity | 6/6 (100%) | 6/6 (100%) | — | unchanged outcome; SC-01/02/03/04 upgraded to verbatim-keyword PASS | +| manual-testing | 4/4 (100%) | 4/4 (100%) | — | unchanged outcome; MT-N1/MT-N2 now doubly reinforced (explicit cross-reference on both sides of each decoy pair) | +| setup-ops | 4/4 (100%) | 4/4 (100%) | — | unchanged outcome | +| planning-processes | 10/10 (100%) | 10/10 (100%) | — | unchanged outcome; PP-N1/PP-N3 doubly reinforced | +| execution-orchestrators | 7/7 (100%) | 7/7 (100%) | — | unchanged outcome; EO-N3 doubly reinforced (review's description now explicitly names the sanity-check decoy) | + +**No description was reverted.** The eval ran once against the full rewritten set; every family +held or improved, so no iterate-and-revert cycle (per the story's Edge Case rule) was triggered. + +## The 3 baseline ambiguities — resolution + +### AD-12 / PB-N2 (assess-pm vs setup-pm) + +**Root cause (baseline)**: both descriptions claimed tool *selection* — assess-pm "proposes a +tool choice", setup-pm "guiding selection from supported options". + +**Fix**: removed "selection" language from setup-pm entirely; the split is now by **verb**, not +by decision-state: + +- `assess-pm`: "Evaluates and recommends which project management tool fits this project (Jira, + Linear, GitHub Projects, etc.) when the choice is still open — proposes a choice, doesn't + configure anything. `/setup-pm` configures the tool once picked; otherwise the caller persists + the proposal via `/record-decision`." +- `setup-pm`: "Configures the project management tool — creates/wires it up, applies its + implementation guide, updates way-of-working, records the decision — whether the tool was + already chosen or picked here. Invoke directly to set up a tracker ('configure Jira', 'set up + GitHub Projects'). Composed by `/bootstrap`; `/assess-pm` delegates here once a tool is picked." + +`assess-pm` owns *recommend/evaluate* ("haven't picked... what should we use", "recommend where +to track work items"); `setup-pm` owns *configure/set up* ("configure Jira", "set up GitHub +Projects", "we already decided — set it up"). Neither description shares the ambiguous "selection" +word anymore, so a prompt names at most one verb. + +**Result**: AD-12 ("recommend where we should track our work items") -> assess-pm only, clean. +PB-N2 ("haven't picked a tracker — what should we use") -> assess-pm only, clean. AD-N1 / PB-03 +(the setup-pm-side prompts) remain clean, now on a stronger "configure"/"set up" verbatim match. + +### AD-14 (assess-stack vs verify-adoption) + +**Root cause (baseline)**: assess-stack's implementation-phase branch ("add dependency") was +buried in the cryptic clause "implementation (add dependency)"; verify-adoption's "checks code and +configuration against project adoption files" claimed the same prompt. + +**Fix**: made the branch explicit with the exact prompt phrasing, and added an explicit +forward/backward-looking distinction on both sides: + +- `assess-stack`: "...when the choice is open: full evaluation at bootstrap, or a single new + dependency during implementation ('should we add Redis', 'is this new dependency consistent + with our stack'). Doesn't audit code already written (that's `/verify-adoption`)." +- `verify-adoption`: "Detects conformity/non-conformity of **already-written** code and + configuration against the project's adopted decisions... a compliance audit, not a + new-choice evaluation (that's `/assess-stack` and siblings)." + +The distinguishing predicate is **already-written vs proposed**: Redis in AD-14 is a dependency +being *proposed*, not code already in the repo, so assess-stack's verbatim example wins and +verify-adoption's own description now explicitly disclaims new-choice prompts. + +**Result**: AD-14 -> assess-stack only, clean (near-verbatim match to the description's own +example phrasing). + +## Per-prompt results (after) + +Verdict key: PASS / AMBIGUOUS / FAIL. Notes flag near-ties resolved by judgment, and cases where +the rewrite turned a judgment-call PASS into a verbatim-match PASS (marked "upgraded"). + +### router + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| RT-01 | ST | next | next | PASS | | +| RT-02 | ST | next | next | PASS | | +| RT-N1 | SNT | refine-story | refine-story | PASS | pull: next ("what to work on"); resolved by refine-story's "Todo to Refined" branch — unchanged from baseline | + +### assess-decision + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| AD-01 | ST | assess-ai | assess-ai | PASS | | +| AD-02 | ST | assess-ai | assess-ai | PASS | upgraded: description now names "Copilot" directly, no more near-tie with assess-stack | +| AD-03 | ST | assess-architecture | assess-architecture | PASS | | +| AD-04 | ST | assess-architecture | assess-architecture | PASS | | +| AD-05 | ST | assess-infrastructure | assess-infrastructure | PASS | | +| AD-06 | ST | assess-infrastructure | assess-infrastructure | PASS | | +| AD-07 | ST | assess-methodology | assess-methodology | PASS | | +| AD-08 | ST | assess-methodology | assess-methodology | PASS | upgraded: "iterations, ceremonies, flow" now literal in the description | +| AD-09 | ST | assess-observability | assess-observability | PASS | | +| AD-10 | ST | assess-observability | assess-observability | PASS | upgraded: "telemetry" now literal in the description | +| AD-11 | ST | assess-pm | assess-pm | PASS | | +| AD-12 | ST | assess-pm | assess-pm | PASS | was AMBIGUOUS (assess-pm, setup-pm) — resolved, see above | +| AD-13 | ST | assess-stack | assess-stack | PASS | | +| AD-14 | ST | assess-stack | assess-stack | PASS | was AMBIGUOUS (assess-stack, verify-adoption) — resolved, see above | +| AD-15 | ST | assess-testing | assess-testing | PASS | | +| AD-16 | ST | assess-testing | assess-testing | PASS | near-tie: "coverage" also in analyze-code-quality; resolved because the prompt sets a forward target ("aim for") vs analyze-code-quality's report-on-current-state framing — same judgment call as baseline | +| AD-N1 | SNT | setup-pm | setup-pm | PASS | now a verbatim match: description literally says "set up GitHub Projects" | +| AD-N2 | SNT | record-decision | record-decision | PASS | assess-stack now explicitly requires "the choice is open"; this prompt is an already-made decision | +| AD-N3 | SNT | none | none | PASS | felt pull toward the assess-* family from the bare word "assess"; no description covers security — unchanged from baseline | +| AD-N4 | SNT | none | none | PASS | assess-testing explicitly states "doesn't write tests itself" | + +### analyze-report + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| AR-01 | ST | analyze-code-quality | analyze-code-quality | PASS | | +| AR-02 | ST | analyze-code-quality | analyze-code-quality | PASS | | +| AR-03 | ST | analyze-debt | analyze-debt | PASS | | +| AR-04 | ST | analyze-debt | analyze-debt | PASS | | +| AR-N1 | SNT | verify-quality | verify-quality | PASS | "pass/fail per gate" vs analyze-code-quality's "report on demand" — clean split | +| AR-N2 | SNT | none | none | PASS | pull: analyze-debt ("debt" keyword); defused by "writes no files... never blocks a PR" | + +### verification + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| VF-01 | ST | verify-quality | verify-quality | PASS | | +| VF-02 | ST | verify-quality | verify-quality | PASS | upgraded: "invoke directly before pushing to check gates on demand" is a near-verbatim match | +| VF-03 | ST | verify-done | verify-done | PASS | upgraded: description literally includes "'is PR #42 actually done'" | +| VF-04 | ST | verify-adoption | verify-adoption | PASS | | +| VF-N1 | SNT | none | none | PASS | verify-quality checks, doesn't fix | +| VF-N2 | SNT | review | review | PASS | review's "to decide whether it merges" wins over verify-done's DoD-only scope | + +### decision-recording + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| DR-01 | ST | record-decision | record-decision | PASS | | +| DR-02 | ST | record-decision | record-decision | PASS | | +| DR-N1 | SNT | assess-stack | assess-stack | PASS | assess-stack now names "database" explicitly; record-decision requires "already made" framing, absent here | + +### pm-and-backlog + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| PB-01 | ST | write-issue | write-issue | PASS | upgraded: "bug" now literal in the description's template list | +| PB-02 | ST | write-issue | write-issue | PASS | | +| PB-03 | ST | setup-pm | setup-pm | PASS | upgraded: "configure Jira ... updates way-of-working" is a near-verbatim match | +| PB-04 | ST | estimate | estimate | PASS | upgraded: description literally includes "'estimate story #87'" | +| PB-N1 | SNT | plan-tasks | plan-tasks | PASS | | +| PB-N2 | SNT | assess-pm | assess-pm | PASS | was AMBIGUOUS (assess-pm, setup-pm) — resolved, see above | + +### ddd-mapping + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| DM-01 | ST | map-subdomains | map-subdomains | PASS | | +| DM-02 | ST | map-contexts | map-contexts | PASS | | +| DM-N1 | SNT | none | none | PASS | | +| DM-N2 | SNT | none | none | PASS | felt pull from "domain" reduced — map-subdomains now reads "DDD subdomains", no longer isolating the bare word "domain" | + +### session-continuity + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| SC-01 | ST | checkpoint | checkpoint | PASS | upgraded: description literally includes "'save our progress on #313'" | +| SC-02 | ST | checkpoint | checkpoint | PASS | upgraded: description literally includes "'resume story #256'" | +| SC-03 | ST | grill | grill | PASS | upgraded: "alignment on a story until shared understanding is confirmed" near-verbatim | +| SC-04 | ST | grill | grill | PASS | upgraded: description literally includes "'grill me on the requirements'" | +| SC-N1 | SNT | none | none | PASS | pull: checkpoint ("progress"); "commit" (git) is a different action than "save/resume progress" | +| SC-N2 | SNT | none | none | PASS | grill interviews, doesn't summarize | + +### manual-testing + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| MT-01 | ST | design-manual-tests | design-manual-tests | PASS | | +| MT-02 | ST | execute-manual-tests | execute-manual-tests | PASS | | +| MT-N1 | SNT | assess-testing | assess-testing | PASS | doubly reinforced: design-manual-tests explicitly redirects to assess-testing, and assess-testing names "pyramid distribution, coverage targets" verbatim | +| MT-N2 | SNT | verify-quality | verify-quality | PASS | doubly reinforced: execute-manual-tests explicitly redirects to verify-quality | + +### setup-ops + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| SO-01 | ST | setup-gates | setup-gates | PASS | "husky hooks" now literal in the description | +| SO-02 | ST | manage-flags | manage-flags | PASS | | +| SO-N1 | SNT | verify-quality | verify-quality | PASS | | +| SO-N2 | SNT | none | none | PASS | config option != feature flag | + +### planning-processes + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| PP-01 | ST | specify-prd | specify-prd | PASS | | +| PP-02 | ST | specify-prd | specify-prd | PASS | upgraded: "filling in a missing/outdated section" near-verbatim | +| PP-03 | ST | plan-initiatives | plan-initiatives | PASS | upgraded: "Turns a PRD into prioritized... initiatives" near-verbatim | +| PP-04 | ST | plan-epics | plan-epics | PASS | | +| PP-05 | ST | plan-stories | plan-stories | PASS | upgraded: "Slices an epic into user stories" near-verbatim | +| PP-06 | ST | plan-tasks | plan-tasks | PASS | "dependency graph" now literal in the description | +| PP-07 | ST | refine-story | refine-story | PASS | "Given-When-Then acceptance criteria" now literal in the description | +| PP-N1 | SNT | write-issue | write-issue | PASS | doubly reinforced: plan-epics explicitly redirects to write-issue | +| PP-N2 | SNT | none | none | PASS | | +| PP-N3 | SNT | estimate | estimate | PASS | doubly reinforced: refine-story explicitly redirects to estimate | + +### execution-orchestrators + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| EO-01 | ST | bootstrap | bootstrap | PASS | | +| EO-02 | ST | bootstrap | bootstrap | PASS | | +| EO-03 | ST | implement | implement | PASS | "opens one PR when the story completes" now literal in the description | +| EO-04 | ST | review | review | PASS | "to decide whether it merges" now literal in the description | +| EO-N1 | SNT | none | none | PASS | pull: implement; a one-line typo is not a refined story | +| EO-N2 | SNT | none | none | PASS | pull: bootstrap ("project setup"); CLI install is not skill territory | +| EO-N3 | SNT | verify-quality | verify-quality | PASS | doubly reinforced: review's description now explicitly names "a quick build/test sanity check" as the non-match, redirecting to verify-quality | + +## Iteration log + +No revert occurred. The rewrite was designed against the baseline's documented root causes before +running this eval (assess-pm/setup-pm split by verb; assess-stack/verify-adoption split by +already-written vs proposed); the eval was then run once, in full, against the result. Every +family held its baseline pass rate or improved, and no prompt regressed — so the story's Edge Case +rule ("if a rewritten description triggers worse, revert that skill's description and iterate") +was not triggered for any of the 34 rewritten skills. + +## Related gates + +- `pnpm skills:conformance` — PASS, 35/35 conformant (frontmatter portability, size limits, + pointer resolution), no warnings (T1's catalog-count fix means the corpus-count warning that + fired in the baseline run no longer applies). +- `pnpm docs:staleness` — PASS, 35 skills / 8 commands in sync. +- `pnpm --filter @pair/knowledge-hub test` (vitest + check:links) — PASS, 101/101 tests, no broken + links. +- `pnpm mdlint:check` — PASS. From eb38af2a5b54a9d499785d1bd54639553b893379 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Tue, 14 Jul 2026 00:02:57 +0200 Subject: [PATCH 2/2] [#313] fix: assess-stack description missing review-composition reach clause Review finding on PR #328 (T3): assess-stack's rewritten description dropped the "composed by /review for unlisted-dependency detection" branch without a reach-clause, unlike sibling verify-adoption which lists both its composers. Body's Review Mode is untouched and still real; only the description signal was missing. Adds the reach clause (dataset + mirror, byte-consistent), plus 2 new should-trigger prompts exercising the branch (AD-14b, AD-14c, both PASS) and an eval addendum documenting the fix. Co-Authored-By: Claude Code --- .../pair-capability-assess-stack/SKILL.md | 2 +- .../.skills/capability/assess-stack/SKILL.md | 2 +- .../eval/results/2026-07-13-after-t3.md | 39 +++++++++++++++++++ .../knowledge-hub/eval/trigger-prompts.json | 12 ++++++ 4 files changed, 53 insertions(+), 2 deletions(-) diff --git a/.claude/skills/pair-capability-assess-stack/SKILL.md b/.claude/skills/pair-capability-assess-stack/SKILL.md index 2913c86b..a9e2ea9a 100644 --- a/.claude/skills/pair-capability-assess-stack/SKILL.md +++ b/.claude/skills/pair-capability-assess-stack/SKILL.md @@ -1,6 +1,6 @@ --- name: pair-capability-assess-stack -description: "Evaluates and recommends the tech stack — languages, frameworks, database, libraries, versions — when the choice is open: full evaluation at bootstrap, or a single new dependency during implementation ('should we add Redis', 'is this new dependency consistent with our stack'). Doesn't audit code already written (that's /pair-capability-verify-adoption). Output-only: emits a proposal + target for /pair-capability-record-decision to persist." +description: "Evaluates and recommends the tech stack — languages, frameworks, database, libraries, versions — when the choice is open: full evaluation at bootstrap, a single new dependency during implementation ('should we add Redis', 'is this new dependency consistent with our stack'), or composed by /pair-process-review when it finds an unlisted dependency in code. Doesn't audit code already written (that's /pair-capability-verify-adoption). Output-only: emits a proposal + target for /pair-capability-record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md index 7a714283..9dda6c9d 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/assess-stack/SKILL.md @@ -1,6 +1,6 @@ --- name: assess-stack -description: "Evaluates and recommends the tech stack — languages, frameworks, database, libraries, versions — when the choice is open: full evaluation at bootstrap, or a single new dependency during implementation ('should we add Redis', 'is this new dependency consistent with our stack'). Doesn't audit code already written (that's /verify-adoption). Output-only: emits a proposal + target for /record-decision to persist." +description: "Evaluates and recommends the tech stack — languages, frameworks, database, libraries, versions — when the choice is open: full evaluation at bootstrap, a single new dependency during implementation ('should we add Redis', 'is this new dependency consistent with our stack'), or composed by /review when it finds an unlisted dependency in code. Doesn't audit code already written (that's /verify-adoption). Output-only: emits a proposal + target for /record-decision to persist." version: 0.5.0 author: Foomakers --- diff --git a/packages/knowledge-hub/eval/results/2026-07-13-after-t3.md b/packages/knowledge-hub/eval/results/2026-07-13-after-t3.md index 9443ce20..eb7cfd44 100644 --- a/packages/knowledge-hub/eval/results/2026-07-13-after-t3.md +++ b/packages/knowledge-hub/eval/results/2026-07-13-after-t3.md @@ -141,6 +141,8 @@ the rewrite turned a judgment-call PASS into a verbatim-match PASS (marked "upgr | AD-12 | ST | assess-pm | assess-pm | PASS | was AMBIGUOUS (assess-pm, setup-pm) — resolved, see above | | AD-13 | ST | assess-stack | assess-stack | PASS | | | AD-14 | ST | assess-stack | assess-stack | PASS | was AMBIGUOUS (assess-stack, verify-adoption) — resolved, see above | +| AD-14b | ST | assess-stack | assess-stack | PASS | added in remediation round 1 (review finding); near-verbatim match to the review-composition reach clause; verify-adoption doesn't fire — its description explicitly disclaims new-choice prompts | +| AD-14c | ST | assess-stack | assess-stack | PASS | added in remediation round 1 (review finding); same reasoning as AD-14b, phrased from `/review`'s perspective ("during review, flag...") | | AD-15 | ST | assess-testing | assess-testing | PASS | | | AD-16 | ST | assess-testing | assess-testing | PASS | near-tie: "coverage" also in analyze-code-quality; resolved because the prompt sets a forward target ("aim for") vs analyze-code-quality's report-on-current-state framing — same judgment call as baseline | | AD-N1 | SNT | setup-pm | setup-pm | PASS | now a verbatim match: description literally says "set up GitHub Projects" | @@ -263,6 +265,43 @@ family held its baseline pass rate or improved, and no prompt regressed — so t rule ("if a rewritten description triggers worse, revert that skill's description and iterate") was not triggered for any of the 34 rewritten skills. +## Remediation round 1 (post-review addendum, 2026-07-14) + +Independent review of PR #328 found one Minor, non-blocking finding: `assess-stack`'s rewritten +description dropped the "composed by `/review` for unlisted-dependency detection" branch without +a reach-clause (unlike `verify-adoption`, which lists both its composers explicitly), and neither +this eval run nor the baseline exercised that branch — the skill's `Review Mode` body section is +real and unchanged, but the description no longer signaled it. + +**Fix**: added a short reach-clause to `assess-stack`'s description covering the missing branch, +mirroring `verify-adoption`'s composer-listing style: + +- Before: "...full evaluation at bootstrap, or a single new dependency during implementation + ('should we add Redis', 'is this new dependency consistent with our stack'). Doesn't audit code + already written..." +- After: "...full evaluation at bootstrap, a single new dependency during implementation ('should + we add Redis', 'is this new dependency consistent with our stack'), **or composed by `/review` + when it finds an unlisted dependency in code**. Doesn't audit code already written..." + +Dataset (`assess-stack`, 477 chars) and mirror (`pair-capability-assess-stack`, 522 chars) updated +in the same commit, byte-consistent under the name-prefix transform (`/review` -> `/pair-process-review` +is the only substantive diff between the two files beyond the pre-existing prefix expansions). + +**New eval coverage**: 2 should-trigger prompts added to `trigger-prompts.json` (family +`assess-decision`) exercising the review/unlisted-dependency branch, run against the fixed +description: + +| Id | Type | Expected | Selected | Verdict | Note | +| -- | ---- | -------- | -------- | ------- | ---- | +| AD-14b | ST | assess-stack | assess-stack | PASS | "This PR adds a dependency that isn't in our tech-stack adoption file — flag it." — near-verbatim match to the new reach clause; `verify-adoption` doesn't fire (its description explicitly disclaims new-choice prompts, and an unlisted dependency awaiting an approve/reject decision is a new choice, not a compliance check of an already-adopted decision) | +| AD-14c | ST | assess-stack | assess-stack | PASS | "During review, flag any package in the diff that isn't in our adopted tech stack yet." — same reasoning as AD-14b, phrased from `/review`'s perspective | + +Both PASS, no ambiguity. Corpus grand total after this round: **81/81 prompts, 100%** (79 from +the original T3 run + 2 new, all PASS). No description was reverted in this round either — the +fix only added a previously-missing branch, it did not narrow or contradict any existing one, and +the 2 new prompts plus a re-check of AD-14 (still PASS, unaffected by the addition) confirm no +regression. + ## Related gates - `pnpm skills:conformance` — PASS, 35/35 conformant (frontmatter portability, size limits, diff --git a/packages/knowledge-hub/eval/trigger-prompts.json b/packages/knowledge-hub/eval/trigger-prompts.json index 488c4767..249bcbfc 100644 --- a/packages/knowledge-hub/eval/trigger-prompts.json +++ b/packages/knowledge-hub/eval/trigger-prompts.json @@ -124,6 +124,18 @@ "expected": "assess-stack", "prompt": "I want to add Redis as a dependency — check whether that's consistent with our stack." }, + { + "id": "AD-14b", + "type": "should-trigger", + "expected": "assess-stack", + "prompt": "This PR adds a dependency that isn't in our tech-stack adoption file — flag it." + }, + { + "id": "AD-14c", + "type": "should-trigger", + "expected": "assess-stack", + "prompt": "During review, flag any package in the diff that isn't in our adopted tech stack yet." + }, { "id": "AD-15", "type": "should-trigger",