From 6f7126c79e07524a683a624596792bd34a7a4a0d Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 13 Jul 2026 08:01:28 +0200 Subject: [PATCH 1/3] [#313] fix: T1 next router catalog + correctness fixes - next: catalog 33->35 (add checkpoint+grill to tables and cascades), explicit corpus-derivation note, corrected counts - next: distinguishing predicates on overlapping cascade rows, tie-break co-located with the table - numbering resets fixed: review Step 6.2, refine-story Step 1 - verify-quality: Step 5.C write-exception surfaced in overview + Arguments - grill: never-answer-for-the-human HITL rule promoted to a Core Rule - forward refs marked planned: /brainstorm (#230), /publish-pr (#255) - dataset + .claude mirror byte-consistent Refs: #313 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../pair-capability-checkpoint/SKILL.md | 4 +- .claude/skills/pair-capability-grill/SKILL.md | 12 +++-- .../pair-capability-verify-quality/SKILL.md | 4 ++ .claude/skills/pair-next/SKILL.md | 44 +++++++++++-------- .../skills/pair-process-refine-story/SKILL.md | 32 +++++++------- .claude/skills/pair-process-review/SKILL.md | 4 +- .../.skills/capability/checkpoint/SKILL.md | 4 +- .../dataset/.skills/capability/grill/SKILL.md | 12 +++-- .../capability/verify-quality/SKILL.md | 4 ++ .../dataset/.skills/next/SKILL.md | 44 +++++++++++-------- .../.skills/process/refine-story/SKILL.md | 32 +++++++------- .../dataset/.skills/process/review/SKILL.md | 4 +- 12 files changed, 118 insertions(+), 82 deletions(-) diff --git a/.claude/skills/pair-capability-checkpoint/SKILL.md b/.claude/skills/pair-capability-checkpoint/SKILL.md index 4b0384e1..6d77b922 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 (story #256) and a future /pair-capability-publish-pr as a handoff." +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 (story #256) and a future /pair-capability-publish-pr (planned — #255) as a handoff." version: 0.4.1 author: Foomakers --- @@ -119,7 +119,7 @@ When composed by a future closing phase of `/pair-process-implement` (story #256 - **Input**: `/pair-process-implement` would invoke `/pair-capability-checkpoint` with `$mode=write` between tasks (or on developer request) to persist progress, `$mode=resume` at Phase 0 when re-invoked on a story that may have been interrupted, and remove the checkpoint on story completion (cleanup). - **Output**: Write mode's returned text becomes the session's record of state. Resume mode's parsed state lets `/pair-process-implement` skip re-analysis and jump straight to the first pending task. -When composed by a future `/pair-capability-publish-pr` (companion capability from the same epic split): +When composed by a future `/pair-capability-publish-pr` (planned — #255; companion capability from the same epic split): - **Input**: `/pair-capability-publish-pr` invokes `/pair-capability-checkpoint` with `$mode=write, $persist=false` to obtain a handoff prompt summarizing the story before drafting the PR description. - **Output**: The returned text (not written to file) is embedded directly into the composer's own output — the composer owns persistence. diff --git a/.claude/skills/pair-capability-grill/SKILL.md b/.claude/skills/pair-capability-grill/SKILL.md index c79e5230..3a64cc49 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) and /pair-process-refine-story (phase 0)." +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)." version: 0.4.1 author: Foomakers --- @@ -9,6 +9,12 @@ author: Foomakers Ask one question at a time, always with a recommended answer, after exploring the KB/codebase for anything already answerable. `interview` mode explores a free topic; `sync` mode systematically aligns AI and human on every aspect of a story. Never writes — returns the synthesis to the caller. +## Core Rules + +- **Never answer for the human.** The recommendation attached to each question is a proposal, not a stand-in for consent. If no reply has been given, the turn ends and the session waits for real input — treating a missing reply as acceptance, or drafting what the human "would probably say," breaks the interview. Grill is HITL by design. +- **One question per turn.** Ask exactly one question at a time; never batch multiple questions. +- **Write-free.** Never write adoption files or PM tool issues in any mode; the only file grill ever writes is the optional `.pair/working/` handoff, on request or interruption. + ## Arguments | Argument | Required | Description | @@ -23,7 +29,7 @@ Ask one question at a time, always with a recommended answer, after exploring th ### Interview Mode (default) -Freeform exploration of `$topic`. No fixed checklist — the question queue grows from what Step 1's exploration leaves open and from what answers reveal. Used standalone or composed by `/pair-process-brainstorm` phase 1 to produce a raw requirements blob. +Freeform exploration of `$topic`. No fixed checklist — the question queue grows from what Step 1's exploration leaves open and from what answers reveal. Used standalone or composed by `/pair-process-brainstorm` (phase 1, planned — #230) to produce a raw requirements blob. ### Sync Mode @@ -132,7 +138,7 @@ SYNTHESIS: ## Composition Interface -When composed by `/pair-process-brainstorm` (phase 1): +When composed by `/pair-process-brainstorm` (phase 1, planned — #230): - **Input**: `$mode` omitted (defaults `interview`); `$topic` from the free theme text or the `$root` issue's body; `$context` carries the issue if `$root` was given. - **Output**: Returns the raw requirements blob (R3.7). `/pair-process-brainstorm` carries it into phase 2 (domain integration) — grill never touches the PM tool or adoption files itself. diff --git a/.claude/skills/pair-capability-verify-quality/SKILL.md b/.claude/skills/pair-capability-verify-quality/SKILL.md index 1e3f1274..699ff528 100644 --- a/.claude/skills/pair-capability-verify-quality/SKILL.md +++ b/.claude/skills/pair-capability-verify-quality/SKILL.md @@ -14,12 +14,16 @@ Validate the current codebase against quality gates. Two sources of truth: Only check gates that are not already passing. +**Read-only, with one exception**: every gate only runs existing commands and modifies nothing — except **Step 5.C** (first-time custom-gate setup), the skill's ONLY write, which on a first run with no Custom Gate Registry writes the registry table or an opt-out marker to way-of-working.md (once). + ## Arguments | Argument | Required | Description | | -------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `$scope` | No | Limit checking: `code-quality`, `tests`, `lint`, `all`, or any custom scope key from adoption (default: `all`) | +> **Write note**: this skill is read-only except **Step 5.C** — first-time custom-gate setup writes the Custom Gate Registry or an opt-out marker to way-of-working.md once. No other step writes anything. + ## Algorithm Execute each gate in order. For every gate, follow the **check → skip → act → verify** pattern. diff --git a/.claude/skills/pair-next/SKILL.md b/.claude/skills/pair-next/SKILL.md index fdc5d6d3..b2a3010b 100644 --- a/.claude/skills/pair-next/SKILL.md +++ b/.claude/skills/pair-next/SKILL.md @@ -7,9 +7,11 @@ author: Foomakers # /pair-next — Project Navigator -Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 33-skill catalog across all lifecycle phases. +Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 35-skill catalog across all lifecycle phases. -## Skill Catalog (33 skills) +## Skill Catalog (35 skills) + +The catalog is **derived from the installed corpus**: every installed skill must appear here — 9 process + 25 capability + `/pair-next` itself = 35. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together. ### Process Skills (9) @@ -25,13 +27,15 @@ Analyze project state and recommend the single most relevant next skill to invok | `/pair-process-implement` | Sprint Execution | Implement story tasks with TDD | | `/pair-process-review` | Sprint Execution | Review PR through structured phases | -### Capability Skills (23) +### Capability Skills (25) | Skill | Category | Description | | -------------------- | ------------ | ----------------------------------------------- | | `/pair-capability-map-subdomains` | Domain Modeling | Scoped DDD subdomain placement (+ Volatility) | | `/pair-capability-map-contexts` | Domain Modeling | Scoped DDD bounded-context placement + relationship assessment | +| `/pair-capability-grill` | Alignment | Interview engine: explore a topic or sync on a story, one question at a time | | `/pair-capability-record-decision` | Decision | Record ADR or ADL with adoption update | +| `/pair-capability-checkpoint` | Session State | Write/resume story progress checkpoint (work survives context resets) | | `/pair-capability-write-issue` | PM Tool | Create/update issues in adopted PM tool | | `/pair-capability-setup-pm` | PM Tool | Configure project management tool | | `/pair-capability-verify-quality` | Quality | Check quality gates against codebase | @@ -93,24 +97,28 @@ All adoption files are populated. Query the PM tool to determine backlog state. | # | Condition | Suggestion | Rationale | | --- | ---------------------------------------------------------------- | ------------------- | ------------------------------------------- | -| 5 | No initiatives or epics exist in PM tool | `/pair-process-plan-initiatives` | Strategic planning needed | -| 6 | Initiatives exist but no epics | `/pair-process-plan-epics` | Epic decomposition needed | -| 7 | Epics exist but no user stories | `/pair-process-plan-stories` | Story breakdown needed | -| 8 | Stories resolve to macrostate `Draft` (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | `/pair-process-refine-story` | Stories need refinement before work | -| 9 | Stories resolve to macrostate `Ready` but have no task breakdown | `/pair-process-plan-tasks` | Tasks must be created before implementation | -| 10 | Tasks or stories resolve to macrostate `Ready` | `/pair-process-implement` | Work is ready to start | -| 11 | Open pull requests, or items resolve to macrostate `Review` | `/pair-process-review` | Code review pending | +| 3 | No initiatives or epics exist in PM tool | `/pair-process-plan-initiatives` | Strategic planning needed | +| 4 | Initiatives exist but no epics | `/pair-process-plan-epics` | Epic decomposition needed | +| 5 | Epics exist but no user stories | `/pair-process-plan-stories` | Story breakdown needed | +| 6 | Open pull requests, or items resolve to macrostate `Review` | `/pair-process-review` | Code review pending — closest to delivery | +| 7 | A story resolves to macrostate `In Progress` AND its checkpoint file exists (`.pair/working/checkpoints/.md`) | `/pair-capability-checkpoint` | Resume interrupted work (`$mode: resume`) before re-analysis | +| 8 | Stories resolve to macrostate `Ready` AND a task breakdown exists | `/pair-process-implement` | Work is ready to start | +| 9 | Stories resolve to macrostate `Ready` but have NO task breakdown | `/pair-process-plan-tasks` | Tasks must be created before implementation | +| 10 | Stories resolve to macrostate `Draft` (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | `/pair-process-refine-story` | Stories need refinement before work | + +**Tie-break**: on a real backlog several of rows 6–10 can hold at once (e.g. Draft stories AND an open PR). Row order resolves this — rows are sorted by delivery proximity (`/pair-process-review` > `/pair-capability-checkpoint` > `/pair-process-implement` > `/pair-process-plan-tasks` > `/pair-process-refine-story`): evaluate top-to-bottom, stop at the first match. For a single item the distinguishing predicates (macrostate, task breakdown present/absent, checkpoint file present/absent) make rows 7–10 mutually exclusive; across items, row order decides. ### Step 4: Capability Skill Suggestions -If no process skill matched in Steps 2-3, check for capability skill opportunities: +If no process skill matched in Steps 2-3, check for capability skill opportunities (same rule: evaluate in order, stop at the first match): | # | Condition | Suggestion | Rationale | | --- | ------------------------------------------------------------------------ | -------------------- | ---------------------------------------------- | -| 12 | Quality gate not configured (no Quality Gates section in way-of-working) | `/pair-capability-setup-gates` | Quality gates should be established | -| 13 | Tech stack has unlisted dependencies detected | `/pair-capability-assess-stack` | Stack registry needs updating | -| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/pair-capability-assess-debt` | Debt should be cataloged and prioritized | -| 15 | No estimation methodology adopted in way-of-working | `/pair-capability-estimate` | Estimation process should be established | +| 11 | Quality gate not configured (no Quality Gates section in way-of-working) | `/pair-capability-setup-gates` | Quality gates should be established | +| 12 | Tech stack has unlisted dependencies detected | `/pair-capability-assess-stack` | Stack registry needs updating | +| 13 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/pair-capability-assess-debt` | Debt should be cataloged and prioritized | +| 14 | No estimation methodology adopted in way-of-working | `/pair-capability-estimate` | Estimation process should be established | +| 15 | A backlog item or topic carries open questions or unclear scope (question markers, conflicting comments) that block planning | `/pair-capability-grill` | Structured one-question-at-a-time alignment before planning | ### Step 5: Fallback @@ -145,11 +153,11 @@ Then ask: "Shall I run `/skill-name`?" - If the PM tool is not accessible (no MCP connection, no credentials), skip Step 3 and report: "PM tool not accessible — recommendation based on adoption files only." - If adoption files cannot be read (not installed yet), suggest `/pair-process-bootstrap` as the entry point. - If way-of-working.md has no `## State Mapping` section, canonical macrostate names are assumed — this is the zero-configuration default, not a degradation. -- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating Step 8's condition as unresolvable. +- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 10's condition as unresolvable. ## Notes - This skill is read-only: it inspects state but never modifies files or PM tool data. -- When multiple items are actionable (e.g., tasks to implement AND PRs to review), prefer the item closest to delivery (`/pair-process-review` > `/pair-process-implement` > `/pair-process-plan-tasks`). +- Row order encodes the tie-break (delivery proximity) — see the **Tie-break** note under the Step 3 table. - Re-run `/pair-next` after completing any skill to get an updated recommendation. -- **Full catalog coverage**: any of the 33 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (Step 4) or process-skill composition. +- **Full catalog coverage**: any of the 35 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (rows 7 `/pair-capability-checkpoint`, 11-15 including `/pair-capability-grill`) or process-skill composition. diff --git a/.claude/skills/pair-process-refine-story/SKILL.md b/.claude/skills/pair-process-refine-story/SKILL.md index 48e572c8..8cd8b313 100644 --- a/.claude/skills/pair-process-refine-story/SKILL.md +++ b/.claude/skills/pair-process-refine-story/SKILL.md @@ -43,25 +43,25 @@ Transform a user story from rough breakdown (Todo) into a development-ready spec 1. **Check**: Read the current story body and classify each section as **present** or **missing**: -| Section | Detection | -| ------------------------------------- | -------------------------------------------------------------------------- | -| Story Statement | Has `**As a**` / `**I want**` / `**So that**` with non-placeholder content | -| Epic Context | Has `**Parent Epic**` with actual link | -| Acceptance Criteria (Given-When-Then) | Has `**Given**` / `**When**` / `**Then**` blocks | -| Business Rules | Has non-placeholder business rules | -| Edge Cases | Has non-placeholder edge case handling | -| Technical Analysis | Has `### Implementation Approach` or `### Strategy` with content | -| Technical Risks | Has risk table with entries | -| Definition of Done | Has DoD checklist with items | -| Story Sizing | Has `**Final Story Points**` with value | -| Dependencies | Has dependency information | -| Validation Strategy | Has testing approach | - -1. **Act**: Determine refinement state: + | Section | Detection | + | ------------------------------------- | -------------------------------------------------------------------------- | + | Story Statement | Has `**As a**` / `**I want**` / `**So that**` with non-placeholder content | + | Epic Context | Has `**Parent Epic**` with actual link | + | Acceptance Criteria (Given-When-Then) | Has `**Given**` / `**When**` / `**Then**` blocks | + | Business Rules | Has non-placeholder business rules | + | Edge Cases | Has non-placeholder edge case handling | + | Technical Analysis | Has `### Implementation Approach` or `### Strategy` with content | + | Technical Risks | Has risk table with entries | + | Definition of Done | Has DoD checklist with items | + | Story Sizing | Has `**Final Story Points**` with value | + | Dependencies | Has dependency information | + | Validation Strategy | Has testing approach | + +2. **Act**: Determine refinement state: - **All sections present** → story is already Refined. Offer selective update (Step 6). - **Some sections present** → partial refinement. Resume from first missing section (Steps 2–5). - **No sections (only Initial Breakdown)** → full refinement needed (Steps 2–5). -2. **Verify**: Refinement state determined. Report: +3. **Verify**: Refinement state determined. Report: > Refinement state: [N/M sections complete]. [Resuming from: Section X | Full refinement | Already refined — offering update]. diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 2a246191..23c42c1e 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -268,7 +268,7 @@ Based on compiled findings: Refs: # ``` -1. **Act** (BLOCKING): Present to reviewer for confirmation: +2. **Act** (BLOCKING): Present to reviewer for confirmation: > **Merge commit message:** > @@ -278,7 +278,7 @@ Based on compiled findings: > > Confirm or edit? -1. **Verify**: Reviewer confirms message. +3. **Verify**: Reviewer confirms message. ### Step 6.3: Merge PR diff --git a/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/checkpoint/SKILL.md index e7d0550b..51994bfa 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 (story #256) and a future /publish-pr as a handoff." +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 (story #256) and a future /publish-pr (planned — #255) as a handoff." version: 0.4.1 author: Foomakers --- @@ -119,7 +119,7 @@ When composed by a future closing phase of `/implement` (story #256): - **Input**: `/implement` would invoke `/checkpoint` with `$mode=write` between tasks (or on developer request) to persist progress, `$mode=resume` at Phase 0 when re-invoked on a story that may have been interrupted, and remove the checkpoint on story completion (cleanup). - **Output**: Write mode's returned text becomes the session's record of state. Resume mode's parsed state lets `/implement` skip re-analysis and jump straight to the first pending task. -When composed by a future `/publish-pr` (companion capability from the same epic split): +When composed by a future `/publish-pr` (planned — #255; companion capability from the same epic split): - **Input**: `/publish-pr` invokes `/checkpoint` with `$mode=write, $persist=false` to obtain a handoff prompt summarizing the story before drafting the PR description. - **Output**: The returned text (not written to file) is embedded directly into the composer's own output — the composer owns persistence. diff --git a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md index 56f7eb8c..c7de7b14 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) and /refine-story (phase 0)." +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)." version: 0.4.1 author: Foomakers --- @@ -9,6 +9,12 @@ author: Foomakers Ask one question at a time, always with a recommended answer, after exploring the KB/codebase for anything already answerable. `interview` mode explores a free topic; `sync` mode systematically aligns AI and human on every aspect of a story. Never writes — returns the synthesis to the caller. +## Core Rules + +- **Never answer for the human.** The recommendation attached to each question is a proposal, not a stand-in for consent. If no reply has been given, the turn ends and the session waits for real input — treating a missing reply as acceptance, or drafting what the human "would probably say," breaks the interview. Grill is HITL by design. +- **One question per turn.** Ask exactly one question at a time; never batch multiple questions. +- **Write-free.** Never write adoption files or PM tool issues in any mode; the only file grill ever writes is the optional `.pair/working/` handoff, on request or interruption. + ## Arguments | Argument | Required | Description | @@ -23,7 +29,7 @@ Ask one question at a time, always with a recommended answer, after exploring th ### Interview Mode (default) -Freeform exploration of `$topic`. No fixed checklist — the question queue grows from what Step 1's exploration leaves open and from what answers reveal. Used standalone or composed by `/brainstorm` phase 1 to produce a raw requirements blob. +Freeform exploration of `$topic`. No fixed checklist — the question queue grows from what Step 1's exploration leaves open and from what answers reveal. Used standalone or composed by `/brainstorm` (phase 1, planned — #230) to produce a raw requirements blob. ### Sync Mode @@ -132,7 +138,7 @@ SYNTHESIS: ## Composition Interface -When composed by `/brainstorm` (phase 1): +When composed by `/brainstorm` (phase 1, planned — #230): - **Input**: `$mode` omitted (defaults `interview`); `$topic` from the free theme text or the `$root` issue's body; `$context` carries the issue if `$root` was given. - **Output**: Returns the raw requirements blob (R3.7). `/brainstorm` carries it into phase 2 (domain integration) — grill never touches the PM tool or adoption files itself. 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 b39e7273..47ccc7c4 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/verify-quality/SKILL.md @@ -14,12 +14,16 @@ Validate the current codebase against quality gates. Two sources of truth: Only check gates that are not already passing. +**Read-only, with one exception**: every gate only runs existing commands and modifies nothing — except **Step 5.C** (first-time custom-gate setup), the skill's ONLY write, which on a first run with no Custom Gate Registry writes the registry table or an opt-out marker to way-of-working.md (once). + ## Arguments | Argument | Required | Description | | -------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `$scope` | No | Limit checking: `code-quality`, `tests`, `lint`, `all`, or any custom scope key from adoption (default: `all`) | +> **Write note**: this skill is read-only except **Step 5.C** — first-time custom-gate setup writes the Custom Gate Registry or an opt-out marker to way-of-working.md once. No other step writes anything. + ## Algorithm Execute each gate in order. For every gate, follow the **check → skip → act → verify** pattern. diff --git a/packages/knowledge-hub/dataset/.skills/next/SKILL.md b/packages/knowledge-hub/dataset/.skills/next/SKILL.md index 2e5a9e9c..399698e2 100644 --- a/packages/knowledge-hub/dataset/.skills/next/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/next/SKILL.md @@ -7,9 +7,11 @@ author: Foomakers # /next — Project Navigator -Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 33-skill catalog across all lifecycle phases. +Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 35-skill catalog across all lifecycle phases. -## Skill Catalog (33 skills) +## Skill Catalog (35 skills) + +The catalog is **derived from the installed corpus**: every skill directory under `.skills/` must appear here — 9 process + 25 capability + `/next` itself = 35. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together. ### Process Skills (9) @@ -25,13 +27,15 @@ Analyze project state and recommend the single most relevant next skill to invok | `/implement` | Sprint Execution | Implement story tasks with TDD | | `/review` | Sprint Execution | Review PR through structured phases | -### Capability Skills (23) +### Capability Skills (25) | Skill | Category | Description | | -------------------- | ------------ | ----------------------------------------------- | | `/map-subdomains` | Domain Modeling | Scoped DDD subdomain placement (+ Volatility) | | `/map-contexts` | Domain Modeling | Scoped DDD bounded-context placement + relationship assessment | +| `/grill` | Alignment | Interview engine: explore a topic or sync on a story, one question at a time | | `/record-decision` | Decision | Record ADR or ADL with adoption update | +| `/checkpoint` | Session State | Write/resume story progress checkpoint (work survives context resets) | | `/write-issue` | PM Tool | Create/update issues in adopted PM tool | | `/setup-pm` | PM Tool | Configure project management tool | | `/verify-quality` | Quality | Check quality gates against codebase | @@ -93,24 +97,28 @@ All adoption files are populated. Query the PM tool to determine backlog state. | # | Condition | Suggestion | Rationale | | --- | ---------------------------------------------------------------- | ------------------- | ------------------------------------------- | -| 5 | No initiatives or epics exist in PM tool | `/plan-initiatives` | Strategic planning needed | -| 6 | Initiatives exist but no epics | `/plan-epics` | Epic decomposition needed | -| 7 | Epics exist but no user stories | `/plan-stories` | Story breakdown needed | -| 8 | Stories resolve to macrostate `Draft` (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | `/refine-story` | Stories need refinement before work | -| 9 | Stories resolve to macrostate `Ready` but have no task breakdown | `/plan-tasks` | Tasks must be created before implementation | -| 10 | Tasks or stories resolve to macrostate `Ready` | `/implement` | Work is ready to start | -| 11 | Open pull requests, or items resolve to macrostate `Review` | `/review` | Code review pending | +| 3 | No initiatives or epics exist in PM tool | `/plan-initiatives` | Strategic planning needed | +| 4 | Initiatives exist but no epics | `/plan-epics` | Epic decomposition needed | +| 5 | Epics exist but no user stories | `/plan-stories` | Story breakdown needed | +| 6 | Open pull requests, or items resolve to macrostate `Review` | `/review` | Code review pending — closest to delivery | +| 7 | A story resolves to macrostate `In Progress` AND its checkpoint file exists (`.pair/working/checkpoints/.md`) | `/checkpoint` | Resume interrupted work (`$mode: resume`) before re-analysis | +| 8 | Stories resolve to macrostate `Ready` AND a task breakdown exists | `/implement` | Work is ready to start | +| 9 | Stories resolve to macrostate `Ready` but have NO task breakdown | `/plan-tasks` | Tasks must be created before implementation | +| 10 | Stories resolve to macrostate `Draft` (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | `/refine-story` | Stories need refinement before work | + +**Tie-break**: on a real backlog several of rows 6–10 can hold at once (e.g. Draft stories AND an open PR). Row order resolves this — rows are sorted by delivery proximity (`/review` > `/checkpoint` > `/implement` > `/plan-tasks` > `/refine-story`): evaluate top-to-bottom, stop at the first match. For a single item the distinguishing predicates (macrostate, task breakdown present/absent, checkpoint file present/absent) make rows 7–10 mutually exclusive; across items, row order decides. ### Step 4: Capability Skill Suggestions -If no process skill matched in Steps 2-3, check for capability skill opportunities: +If no process skill matched in Steps 2-3, check for capability skill opportunities (same rule: evaluate in order, stop at the first match): | # | Condition | Suggestion | Rationale | | --- | ------------------------------------------------------------------------ | -------------------- | ---------------------------------------------- | -| 12 | Quality gate not configured (no Quality Gates section in way-of-working) | `/setup-gates` | Quality gates should be established | -| 13 | Tech stack has unlisted dependencies detected | `/assess-stack` | Stack registry needs updating | -| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/assess-debt` | Debt should be cataloged and prioritized | -| 15 | No estimation methodology adopted in way-of-working | `/estimate` | Estimation process should be established | +| 11 | Quality gate not configured (no Quality Gates section in way-of-working) | `/setup-gates` | Quality gates should be established | +| 12 | Tech stack has unlisted dependencies detected | `/assess-stack` | Stack registry needs updating | +| 13 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/assess-debt` | Debt should be cataloged and prioritized | +| 14 | No estimation methodology adopted in way-of-working | `/estimate` | Estimation process should be established | +| 15 | A backlog item or topic carries open questions or unclear scope (question markers, conflicting comments) that block planning | `/grill` | Structured one-question-at-a-time alignment before planning | ### Step 5: Fallback @@ -145,11 +153,11 @@ Then ask: "Shall I run `/skill-name`?" - If the PM tool is not accessible (no MCP connection, no credentials), skip Step 3 and report: "PM tool not accessible — recommendation based on adoption files only." - If adoption files cannot be read (not installed yet), suggest `/bootstrap` as the entry point. - If way-of-working.md has no `## State Mapping` section, canonical macrostate names are assumed — this is the zero-configuration default, not a degradation. -- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating Step 8's condition as unresolvable. +- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 10's condition as unresolvable. ## Notes - This skill is read-only: it inspects state but never modifies files or PM tool data. -- When multiple items are actionable (e.g., tasks to implement AND PRs to review), prefer the item closest to delivery (`/review` > `/implement` > `/plan-tasks`). +- Row order encodes the tie-break (delivery proximity) — see the **Tie-break** note under the Step 3 table. - Re-run `/next` after completing any skill to get an updated recommendation. -- **Full catalog coverage**: any of the 33 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (Step 4) or process-skill composition. +- **Full catalog coverage**: any of the 35 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (rows 7 `/checkpoint`, 11-15 including `/grill`) or process-skill composition. 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 0ad64a13..0f2e00e0 100644 --- a/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/refine-story/SKILL.md @@ -43,25 +43,25 @@ Transform a user story from rough breakdown (Todo) into a development-ready spec 1. **Check**: Read the current story body and classify each section as **present** or **missing**: -| Section | Detection | -| ------------------------------------- | -------------------------------------------------------------------------- | -| Story Statement | Has `**As a**` / `**I want**` / `**So that**` with non-placeholder content | -| Epic Context | Has `**Parent Epic**` with actual link | -| Acceptance Criteria (Given-When-Then) | Has `**Given**` / `**When**` / `**Then**` blocks | -| Business Rules | Has non-placeholder business rules | -| Edge Cases | Has non-placeholder edge case handling | -| Technical Analysis | Has `### Implementation Approach` or `### Strategy` with content | -| Technical Risks | Has risk table with entries | -| Definition of Done | Has DoD checklist with items | -| Story Sizing | Has `**Final Story Points**` with value | -| Dependencies | Has dependency information | -| Validation Strategy | Has testing approach | - -1. **Act**: Determine refinement state: + | Section | Detection | + | ------------------------------------- | -------------------------------------------------------------------------- | + | Story Statement | Has `**As a**` / `**I want**` / `**So that**` with non-placeholder content | + | Epic Context | Has `**Parent Epic**` with actual link | + | Acceptance Criteria (Given-When-Then) | Has `**Given**` / `**When**` / `**Then**` blocks | + | Business Rules | Has non-placeholder business rules | + | Edge Cases | Has non-placeholder edge case handling | + | Technical Analysis | Has `### Implementation Approach` or `### Strategy` with content | + | Technical Risks | Has risk table with entries | + | Definition of Done | Has DoD checklist with items | + | Story Sizing | Has `**Final Story Points**` with value | + | Dependencies | Has dependency information | + | Validation Strategy | Has testing approach | + +2. **Act**: Determine refinement state: - **All sections present** → story is already Refined. Offer selective update (Step 6). - **Some sections present** → partial refinement. Resume from first missing section (Steps 2–5). - **No sections (only Initial Breakdown)** → full refinement needed (Steps 2–5). -2. **Verify**: Refinement state determined. Report: +3. **Verify**: Refinement state determined. Report: > Refinement state: [N/M sections complete]. [Resuming from: Section X | Full refinement | Already refined — offering update]. diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index 6ce24c6f..a980f02b 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -268,7 +268,7 @@ Based on compiled findings: Refs: # ``` -1. **Act** (BLOCKING): Present to reviewer for confirmation: +2. **Act** (BLOCKING): Present to reviewer for confirmation: > **Merge commit message:** > @@ -278,7 +278,7 @@ Based on compiled findings: > > Confirm or edit? -1. **Verify**: Reviewer confirms message. +3. **Verify**: Reviewer confirms message. ### Step 6.3: Merge PR From 177ed4c9c4752ba8c86f61fa6db9debc8f29143a Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 13 Jul 2026 08:48:20 +0200 Subject: [PATCH 2/3] =?UTF-8?q?[#313]=20fix:=20T1=20review=20remediation?= =?UTF-8?q?=20=E2=80=94=20residual=20counts=20+=20In-Progress=20catch-all?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - way-of-working.md + getting-started.md (dataset+mirror): stale "33 skills" / "30 (11+19)" → 35 (9 process + 25 capability + 1 navigator) - next: add catch-all cascade row (In Progress + no checkpoint → /implement); renumber Step 3 (6-11) and Step 4 (12-16); tie-break notes every In-Progress story is routed, fallback never reached for active work - dataset + .claude mirror byte-consistent - changelogs/decision-log left untouched (historical records) Refs: #313 Addresses PR #325 review findings 1-2 Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/pair-next/SKILL.md | 23 ++++++++++--------- .pair/knowledge/getting-started.md | 2 +- .pair/knowledge/way-of-working.md | 2 +- .../.pair/knowledge/getting-started.md | 2 +- .../dataset/.pair/knowledge/way-of-working.md | 2 +- .../dataset/.skills/next/SKILL.md | 23 ++++++++++--------- 6 files changed, 28 insertions(+), 26 deletions(-) diff --git a/.claude/skills/pair-next/SKILL.md b/.claude/skills/pair-next/SKILL.md index b2a3010b..801b4d97 100644 --- a/.claude/skills/pair-next/SKILL.md +++ b/.claude/skills/pair-next/SKILL.md @@ -102,11 +102,12 @@ All adoption files are populated. Query the PM tool to determine backlog state. | 5 | Epics exist but no user stories | `/pair-process-plan-stories` | Story breakdown needed | | 6 | Open pull requests, or items resolve to macrostate `Review` | `/pair-process-review` | Code review pending — closest to delivery | | 7 | A story resolves to macrostate `In Progress` AND its checkpoint file exists (`.pair/working/checkpoints/.md`) | `/pair-capability-checkpoint` | Resume interrupted work (`$mode: resume`) before re-analysis | -| 8 | Stories resolve to macrostate `Ready` AND a task breakdown exists | `/pair-process-implement` | Work is ready to start | -| 9 | Stories resolve to macrostate `Ready` but have NO task breakdown | `/pair-process-plan-tasks` | Tasks must be created before implementation | -| 10 | Stories resolve to macrostate `Draft` (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | `/pair-process-refine-story` | Stories need refinement before work | +| 8 | A story resolves to macrostate `In Progress` but has NO checkpoint file | `/pair-process-implement` | Continue the in-progress work — `/pair-process-implement` re-derives state from scratch when no checkpoint exists | +| 9 | Stories resolve to macrostate `Ready` AND a task breakdown exists | `/pair-process-implement` | Work is ready to start | +| 10 | Stories resolve to macrostate `Ready` but have NO task breakdown | `/pair-process-plan-tasks` | Tasks must be created before implementation | +| 11 | Stories resolve to macrostate `Draft` (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | `/pair-process-refine-story` | Stories need refinement before work | -**Tie-break**: on a real backlog several of rows 6–10 can hold at once (e.g. Draft stories AND an open PR). Row order resolves this — rows are sorted by delivery proximity (`/pair-process-review` > `/pair-capability-checkpoint` > `/pair-process-implement` > `/pair-process-plan-tasks` > `/pair-process-refine-story`): evaluate top-to-bottom, stop at the first match. For a single item the distinguishing predicates (macrostate, task breakdown present/absent, checkpoint file present/absent) make rows 7–10 mutually exclusive; across items, row order decides. +**Tie-break**: on a real backlog several of rows 6–11 can hold at once (e.g. Draft stories AND an open PR). Row order resolves this — rows are sorted by delivery proximity (`/pair-process-review` > `/pair-capability-checkpoint` > `/pair-process-implement` > `/pair-process-plan-tasks` > `/pair-process-refine-story`): evaluate top-to-bottom, stop at the first match. For a single item the distinguishing predicates (macrostate, checkpoint file present/absent, task breakdown present/absent) make rows 7–11 mutually exclusive; across items, row order decides. Every `In Progress` story matches row 7 or row 8 — the fallback (Step 5) is never reached for active work. ### Step 4: Capability Skill Suggestions @@ -114,11 +115,11 @@ If no process skill matched in Steps 2-3, check for capability skill opportuniti | # | Condition | Suggestion | Rationale | | --- | ------------------------------------------------------------------------ | -------------------- | ---------------------------------------------- | -| 11 | Quality gate not configured (no Quality Gates section in way-of-working) | `/pair-capability-setup-gates` | Quality gates should be established | -| 12 | Tech stack has unlisted dependencies detected | `/pair-capability-assess-stack` | Stack registry needs updating | -| 13 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/pair-capability-assess-debt` | Debt should be cataloged and prioritized | -| 14 | No estimation methodology adopted in way-of-working | `/pair-capability-estimate` | Estimation process should be established | -| 15 | A backlog item or topic carries open questions or unclear scope (question markers, conflicting comments) that block planning | `/pair-capability-grill` | Structured one-question-at-a-time alignment before planning | +| 12 | Quality gate not configured (no Quality Gates section in way-of-working) | `/pair-capability-setup-gates` | Quality gates should be established | +| 13 | Tech stack has unlisted dependencies detected | `/pair-capability-assess-stack` | Stack registry needs updating | +| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/pair-capability-assess-debt` | Debt should be cataloged and prioritized | +| 15 | No estimation methodology adopted in way-of-working | `/pair-capability-estimate` | Estimation process should be established | +| 16 | A backlog item or topic carries open questions or unclear scope (question markers, conflicting comments) that block planning | `/pair-capability-grill` | Structured one-question-at-a-time alignment before planning | ### Step 5: Fallback @@ -153,11 +154,11 @@ Then ask: "Shall I run `/skill-name`?" - If the PM tool is not accessible (no MCP connection, no credentials), skip Step 3 and report: "PM tool not accessible — recommendation based on adoption files only." - If adoption files cannot be read (not installed yet), suggest `/pair-process-bootstrap` as the entry point. - If way-of-working.md has no `## State Mapping` section, canonical macrostate names are assumed — this is the zero-configuration default, not a degradation. -- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 10's condition as unresolvable. +- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 11's condition as unresolvable. ## Notes - This skill is read-only: it inspects state but never modifies files or PM tool data. - Row order encodes the tie-break (delivery proximity) — see the **Tie-break** note under the Step 3 table. - Re-run `/pair-next` after completing any skill to get an updated recommendation. -- **Full catalog coverage**: any of the 35 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (rows 7 `/pair-capability-checkpoint`, 11-15 including `/pair-capability-grill`) or process-skill composition. +- **Full catalog coverage**: any of the 35 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7 `/pair-capability-checkpoint`, rows 12-16 including `/pair-capability-grill`) or process-skill composition. diff --git a/.pair/knowledge/getting-started.md b/.pair/knowledge/getting-started.md index 33ab4c79..b49af046 100644 --- a/.pair/knowledge/getting-started.md +++ b/.pair/knowledge/getting-started.md @@ -81,7 +81,7 @@ Welcome to the AI-Human pairing repository template! This guide provides essenti - **`way-of-working.md`**: Main process documentation – the starting point to understand the full workflow - **`getting-started.md`**: This guide – essential information to get started with the framework -- **`skills-guide.md`**: Full catalog of 30 Agent Skills (11 process + 19 capability) with composition patterns, adoption file mapping, and usage instructions +- **`skills-guide.md`**: Full catalog of 35 Agent Skills (9 process + 25 capability + 1 navigator) with composition patterns, adoption file mapping, and usage instructions - **`how-to/`**: Step-by-step guides for each development phase and LLM collaboration - Process guides (01-11): Operational documentation for each phase - **`assets/`**: Templates, checklists, and document examples (e.g., PRD, bootstrap checklist) diff --git a/.pair/knowledge/way-of-working.md b/.pair/knowledge/way-of-working.md index 01f6a993..2a440679 100644 --- a/.pair/knowledge/way-of-working.md +++ b/.pair/knowledge/way-of-working.md @@ -78,4 +78,4 @@ The process is designed to: 2. **🤖🤝👨‍💻 Code Review** (`/pair-process-review`) → Structured review with adoption compliance, merge flow, and parent cascade 3. **🤖⚡ Status Update** → Automatic story/epic/initiative tracking update (handled by `/pair-process-implement` and `/pair-process-review`) -> **Skill-enabled workflow**: Run `/pair-next` at session start to determine the most relevant skill. See [skills-guide.md](skills-guide.md) for the full catalog of 33 skills. +> **Skill-enabled workflow**: Run `/pair-next` at session start to determine the most relevant skill. See [skills-guide.md](skills-guide.md) for the full catalog of 35 skills. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/getting-started.md b/packages/knowledge-hub/dataset/.pair/knowledge/getting-started.md index 3373f475..e907a75b 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/getting-started.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/getting-started.md @@ -79,7 +79,7 @@ Welcome to the AI-Human pairing repository template! This guide provides essenti - **`way-of-working.md`**: Main process documentation – the starting point to understand the full workflow - **`getting-started.md`**: This guide – essential information to get started with the framework -- **`skills-guide.md`**: Full catalog of 30 Agent Skills (11 process + 19 capability) with composition patterns, adoption file mapping, and usage instructions +- **`skills-guide.md`**: Full catalog of 35 Agent Skills (9 process + 25 capability + 1 navigator) with composition patterns, adoption file mapping, and usage instructions - **`how-to/`**: Step-by-step guides for each development phase and LLM collaboration - Process guides (01-11): Operational documentation for each phase - **`assets/`**: Templates, checklists, and document examples (e.g., PRD, bootstrap checklist) diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/way-of-working.md b/packages/knowledge-hub/dataset/.pair/knowledge/way-of-working.md index ceaf07dd..8cd2b366 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/way-of-working.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/way-of-working.md @@ -78,4 +78,4 @@ The process is designed to: 2. **🤖🤝👨‍💻 Code Review** (`/review`) → Structured review with adoption compliance, merge flow, and parent cascade 3. **🤖⚡ Status Update** → Automatic story/epic/initiative tracking update (handled by `/implement` and `/review`) -> **Skill-enabled workflow**: Run `/next` at session start to determine the most relevant skill. See [skills-guide.md](skills-guide.md) for the full catalog of 33 skills. +> **Skill-enabled workflow**: Run `/next` at session start to determine the most relevant skill. See [skills-guide.md](skills-guide.md) for the full catalog of 35 skills. diff --git a/packages/knowledge-hub/dataset/.skills/next/SKILL.md b/packages/knowledge-hub/dataset/.skills/next/SKILL.md index 399698e2..f07571e5 100644 --- a/packages/knowledge-hub/dataset/.skills/next/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/next/SKILL.md @@ -102,11 +102,12 @@ All adoption files are populated. Query the PM tool to determine backlog state. | 5 | Epics exist but no user stories | `/plan-stories` | Story breakdown needed | | 6 | Open pull requests, or items resolve to macrostate `Review` | `/review` | Code review pending — closest to delivery | | 7 | A story resolves to macrostate `In Progress` AND its checkpoint file exists (`.pair/working/checkpoints/.md`) | `/checkpoint` | Resume interrupted work (`$mode: resume`) before re-analysis | -| 8 | Stories resolve to macrostate `Ready` AND a task breakdown exists | `/implement` | Work is ready to start | -| 9 | Stories resolve to macrostate `Ready` but have NO task breakdown | `/plan-tasks` | Tasks must be created before implementation | -| 10 | Stories resolve to macrostate `Draft` (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | `/refine-story` | Stories need refinement before work | +| 8 | A story resolves to macrostate `In Progress` but has NO checkpoint file | `/implement` | Continue the in-progress work — `/implement` re-derives state from scratch when no checkpoint exists | +| 9 | Stories resolve to macrostate `Ready` AND a task breakdown exists | `/implement` | Work is ready to start | +| 10 | Stories resolve to macrostate `Ready` but have NO task breakdown | `/plan-tasks` | Tasks must be created before implementation | +| 11 | Stories resolve to macrostate `Draft` (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | `/refine-story` | Stories need refinement before work | -**Tie-break**: on a real backlog several of rows 6–10 can hold at once (e.g. Draft stories AND an open PR). Row order resolves this — rows are sorted by delivery proximity (`/review` > `/checkpoint` > `/implement` > `/plan-tasks` > `/refine-story`): evaluate top-to-bottom, stop at the first match. For a single item the distinguishing predicates (macrostate, task breakdown present/absent, checkpoint file present/absent) make rows 7–10 mutually exclusive; across items, row order decides. +**Tie-break**: on a real backlog several of rows 6–11 can hold at once (e.g. Draft stories AND an open PR). Row order resolves this — rows are sorted by delivery proximity (`/review` > `/checkpoint` > `/implement` > `/plan-tasks` > `/refine-story`): evaluate top-to-bottom, stop at the first match. For a single item the distinguishing predicates (macrostate, checkpoint file present/absent, task breakdown present/absent) make rows 7–11 mutually exclusive; across items, row order decides. Every `In Progress` story matches row 7 or row 8 — the fallback (Step 5) is never reached for active work. ### Step 4: Capability Skill Suggestions @@ -114,11 +115,11 @@ If no process skill matched in Steps 2-3, check for capability skill opportuniti | # | Condition | Suggestion | Rationale | | --- | ------------------------------------------------------------------------ | -------------------- | ---------------------------------------------- | -| 11 | Quality gate not configured (no Quality Gates section in way-of-working) | `/setup-gates` | Quality gates should be established | -| 12 | Tech stack has unlisted dependencies detected | `/assess-stack` | Stack registry needs updating | -| 13 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/assess-debt` | Debt should be cataloged and prioritized | -| 14 | No estimation methodology adopted in way-of-working | `/estimate` | Estimation process should be established | -| 15 | A backlog item or topic carries open questions or unclear scope (question markers, conflicting comments) that block planning | `/grill` | Structured one-question-at-a-time alignment before planning | +| 12 | Quality gate not configured (no Quality Gates section in way-of-working) | `/setup-gates` | Quality gates should be established | +| 13 | Tech stack has unlisted dependencies detected | `/assess-stack` | Stack registry needs updating | +| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | `/assess-debt` | Debt should be cataloged and prioritized | +| 15 | No estimation methodology adopted in way-of-working | `/estimate` | Estimation process should be established | +| 16 | A backlog item or topic carries open questions or unclear scope (question markers, conflicting comments) that block planning | `/grill` | Structured one-question-at-a-time alignment before planning | ### Step 5: Fallback @@ -153,11 +154,11 @@ Then ask: "Shall I run `/skill-name`?" - If the PM tool is not accessible (no MCP connection, no credentials), skip Step 3 and report: "PM tool not accessible — recommendation based on adoption files only." - If adoption files cannot be read (not installed yet), suggest `/bootstrap` as the entry point. - If way-of-working.md has no `## State Mapping` section, canonical macrostate names are assumed — this is the zero-configuration default, not a degradation. -- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 10's condition as unresolvable. +- If a board can't distinguish `Draft` from `Ready` (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 11's condition as unresolvable. ## Notes - This skill is read-only: it inspects state but never modifies files or PM tool data. - Row order encodes the tie-break (delivery proximity) — see the **Tie-break** note under the Step 3 table. - Re-run `/next` after completing any skill to get an updated recommendation. -- **Full catalog coverage**: any of the 35 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (rows 7 `/checkpoint`, 11-15 including `/grill`) or process-skill composition. +- **Full catalog coverage**: any of the 35 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7 `/checkpoint`, rows 12-16 including `/grill`) or process-skill composition. From 99f2a4f1caca1986bca82b52abd55e47a7d0e4ef Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 13 Jul 2026 19:58:52 +0200 Subject: [PATCH 3/3] =?UTF-8?q?[#313]=20fix:=20T1=20review=20remediation?= =?UTF-8?q?=20=E2=80=94=20repo-root=20README=20skill=20counts=2033?= =?UTF-8?q?=E2=86=9235?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md:26 "33 idempotent workflows" → 35 - README.md:42 "33 Agent Skills — ..." → 35 - repo-root README not covered by docs:staleness (scans content/docs only), so these had no gate Refs: #313 Addresses PR #325 /pair-process-review finding (residual stale counts) Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 41475b9e..f27b717c 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ This installs the pair Knowledge Base into your project. Your AI assistant reads ## What You Get - **Knowledge Base** — guidelines, how-to guides, and templates for every SDLC phase -- **Agent Skills** — 33 idempotent workflows following the [agentskills.io](https://agentskills.io) open standard +- **Agent Skills** — 35 idempotent workflows following the [agentskills.io](https://agentskills.io) open standard - **Adoption Files** — project-specific decisions (architecture, tech stack, way of working) - **AI-friendly index** — `.pair/llms.txt` for machine-readable KB discovery ([llmstxt.org](https://llmstxt.org)) @@ -39,7 +39,7 @@ Resources managed by pair in this repo: | `.pair/adoption/tech/` | Architecture, tech stack, infrastructure, way of working, 7 ADRs | | `.pair/adoption/product/` | PRD, subdomain model | | `.pair/adoption/decision-log/` | Non-architectural decision records | -| `.claude/skills/` | 33 Agent Skills — process workflows (implement, review, refine) and capabilities (quality gates, estimation, manual testing, debt assessment) | +| `.claude/skills/` | 35 Agent Skills — process workflows (implement, review, refine) and capabilities (quality gates, estimation, manual testing, debt assessment) | | `AGENTS.md` | Universal agent entry point linking to `.pair/` | ## Documentation