From 087f72faf55e9b8ca778c59553512b44436eb207 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter Date: Sun, 10 May 2026 17:18:16 +0100 Subject: [PATCH 1/5] Prevent duplicate skill loading --- skills/debug/references/bug-reviewer-prompt.md | 2 -- skills/debug/references/bug-worker-prompt.md | 2 +- skills/execute/references/worker-feedback-prompt.md | 4 ++-- skills/execute/references/worker-prompt.md | 4 ++-- skills/plan/SKILL.md | 6 +++--- skills/propulsion/SKILL.md | 2 +- skills/review/references/reviewer-prompt.md | 2 -- 7 files changed, 9 insertions(+), 13 deletions(-) diff --git a/skills/debug/references/bug-reviewer-prompt.md b/skills/debug/references/bug-reviewer-prompt.md index cddd4c5..3944ec1 100644 --- a/skills/debug/references/bug-reviewer-prompt.md +++ b/skills/debug/references/bug-reviewer-prompt.md @@ -87,8 +87,6 @@ Use this exact format for your output. These rules are MANDATORY. - Treat the diagnosis gate as required, not advisory. -- ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY. -- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise. - Reject speculative or symptom-only fixes. - Reject missing root-cause evidence, missing fail-then-pass proof or accepted no-test rationale, changes outside the chosen fix hypothesis, or permanent code changes made outside the bug-worker subagent. - Call out missing verification or contradictory evidence explicitly. diff --git a/skills/debug/references/bug-worker-prompt.md b/skills/debug/references/bug-worker-prompt.md index ff30f4e..b98c6bc 100644 --- a/skills/debug/references/bug-worker-prompt.md +++ b/skills/debug/references/bug-worker-prompt.md @@ -60,7 +60,7 @@ Use this exact format for your output. These rules are MANDATORY. - MUST return exactly one `Status:` field with `done`, `blocked`, or `unclear`. -- Load the `tdd` skill NOW before production-code edits. +- ALWAYS load and follow the `tdd` skill. - ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY. - Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise. - NO PRODUCTION CODE before a failing regression test unless `tdd` declares no valuable test and `debug.md` records the rationale plus fallback verification. diff --git a/skills/execute/references/worker-feedback-prompt.md b/skills/execute/references/worker-feedback-prompt.md index 7f76c61..d892c92 100644 --- a/skills/execute/references/worker-feedback-prompt.md +++ b/skills/execute/references/worker-feedback-prompt.md @@ -22,7 +22,7 @@ Follow these steps IN ORDER. Do NOT skip steps. 5. If any finding remains `unclear` after investigation, STOP and return `Status: unclear` with the specific information needed to continue. 6. For every `invalid` finding, keep the implementation unchanged and prepare evidence-backed pushback. 7. For every `valid` finding, load the `tdd` skill, follow it, and make the minimal correct fix. -8. Load any additional recommended skills when needed to validate or fix the reviewed work. +8. Load any additional recommended skills not already active or present in context when needed to validate or fix the reviewed work. 9. Verify the implementation works and conforms to the current phase in `plan.md`. 10. Re-evaluate every current-phase acceptance criterion by ID. 11. Return your implementation report in the exact format below. @@ -73,7 +73,7 @@ These rules are MANDATORY. - Status CAN ONLY be `done` when every finding is resolved, every valid finding is fixed, every invalid finding has evidence-backed pushback, and every acceptance criterion is re-evaluated. - DO NOT change code for invalid findings. - DO NOT make speculative changes beyond the current phase or review findings. -- ALWAYS load and use the `tdd` skill before fixing valid findings. +- ALWAYS use the `tdd` skill to fix valid findings, loading it only when it is not already active or present in context. - MUST verify implementation against the plan before claiming `Status: done`. - ENSURE pushback is technical, evidence-based, and specific enough for the reviewer to verify or challenge. - ALWAYS follow the output structure and section order exactly as specified. diff --git a/skills/execute/references/worker-prompt.md b/skills/execute/references/worker-prompt.md index 0aebfcd..9f453e5 100644 --- a/skills/execute/references/worker-prompt.md +++ b/skills/execute/references/worker-prompt.md @@ -57,7 +57,7 @@ Use this exact format for your output. These rules are MANDATORY. - MUST start by reviewing the current phase details in `plan.md`. -- ALWAYS load any recommended skills and gather additional context before asking questions or implementing. +- ALWAYS load missing recommended skills and gather additional context before asking questions or implementing. - ALWAYS ask questions if anything in the task is unclear, NEVER guess or make assumptions. - ALWAYS load and use the `tdd` skill. - MUST verify implementation against the plan before claiming `Status: done`. @@ -68,7 +68,7 @@ These rules are MANDATORY. Do NOT output your response until ALL items are complete. - [ ] Reviewed the current phase details in `plan.md`. -- [ ] Loaded any recommended skills and gathered additional context. +- [ ] Loaded any missing recommended skills and gathered additional context. - [ ] Asked clarifying questions for any unclear requirements, scope, or repo state. - [ ] Followed the `tdd` skill to implement the requirements. - [ ] Verified implementation works and conforms to the plan. diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md index 0f5e1ae..822757c 100644 --- a/skills/plan/SKILL.md +++ b/skills/plan/SKILL.md @@ -20,7 +20,7 @@ Follow these steps IN ORDER. Do NOT skip steps. 1. Review the approved `prd.md` to get a complete understanding of the feature. 2. Explore relevant areas of the codebase for fresh context. -3. Load any non-Propulsion skills relevant to the PRD and use them to help inform the plan. +3. Load any non-Propulsion skills relevant to the PRD that are not already active or present in context, and use them to help inform the plan. 4. Write `docs/propulsion/{yyyymmdd}-{feature-name}/plan.md` using the template in [references/plan-template.md](references/plan-template.md). 5. Start a fresh plan review subagent with the prompt in [references/plan-reviewer-prompt.md](references/plan-reviewer-prompt.md). 6. Review and implement feedback from the plan review. @@ -32,7 +32,7 @@ Follow these steps IN ORDER. Do NOT skip steps. These rules are MANDATORY. -- NEVER skip reviewing the PRD, exploring the codebase, or loading relevant skills. +- NEVER skip reviewing the PRD, exploring the codebase, or loading missing relevant skills. - ALWAYS use the plan template reference for structure, section order, and completion rules. - NEVER print the full plan in the chat, ONLY write it to the file. - MUST use ALL information from the PRD, DO NOT leave any details out even if they seem obvious or minor. @@ -53,7 +53,7 @@ Do NOT leave this skill until ALL items are complete. Once the completion gate is fully checked: -- If `prd.md` is approved, enter the `execute` skill. +- If `plan.md` is approved, enter the `execute` skill. ## References diff --git a/skills/propulsion/SKILL.md b/skills/propulsion/SKILL.md index 27f6869..019d7bd 100644 --- a/skills/propulsion/SKILL.md +++ b/skills/propulsion/SKILL.md @@ -38,6 +38,7 @@ These rules are MANDATORY. - MUST route feature and product-scope work to `brainstorm` (new features, unclear scope, UX/product shaping, requirements discovery, behaviour changes, refactors, optimisations). - ALWAYS fall back to `brainstorm` if the request is ambiguous. - DO NOT leave a Propulsion skill until ALL completion gate items are complete. +- NEVER reload skills (Propulsion or non-Propulsion) that are already active or present in context; continue following the loaded copy instead. - NEVER rationalise skipping Propulsion with thoughts like: - "I need more context first" - "I'll inspect the repo first" @@ -52,7 +53,6 @@ Do NOT leave this skill until ALL items are complete. - [ ] Routed concrete failures to `debug`. - [ ] Routed feature and product-scope work to `brainstorm`. - [ ] Emitted the route-specific required response before any other user-visible text. -- [ ] Loaded the chosen skill immediately. ## References diff --git a/skills/review/references/reviewer-prompt.md b/skills/review/references/reviewer-prompt.md index faf2fd6..23cc3ee 100644 --- a/skills/review/references/reviewer-prompt.md +++ b/skills/review/references/reviewer-prompt.md @@ -50,8 +50,6 @@ Return `[]` when no candidates survive the reviewer pass. - ALWAYS stay inside the assigned axis. - ALWAYS stay inside the allowed review scope and allowed context. -- ALWAYS check for non-Propulsion skills that are relevant to this task and load them IMMEDIATELY using the skill tool. -- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise. - DO return only normalised candidates. - MUST replace the output placeholders with the exact JSON object shape from `references/issue-schema.md` before dispatching the reviewer. - DO NOT write final report sections, verdicts, or fix patches. From 9a0dd31e1dc31dd881672d332584192a73d4ad5b Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter Date: Sun, 10 May 2026 17:32:45 +0100 Subject: [PATCH 2/5] Remove duplicate section --- skills/plan/references/plan-template.md | 57 ------------------------- 1 file changed, 57 deletions(-) diff --git a/skills/plan/references/plan-template.md b/skills/plan/references/plan-template.md index 7e66bdf..5e45c33 100644 --- a/skills/plan/references/plan-template.md +++ b/skills/plan/references/plan-template.md @@ -85,63 +85,6 @@ Each acceptance criterion MUST reference at least one PRD user story, functional Describe the public behaviours and seams that MUST be tested for this phase. -| Test Level | Required Coverage | -| --------------------- | ----------------- | -| Unit | | -| Feature / Integration | | -| Browser / UI | | -| Regression | | -| Manual Verification | | - -## Phase 2: - -**Status**: [ ] Phase complete - -**Goal**: Describe the narrow end-to-end behaviour this phase implements. The goal MUST describe a complete user-visible, system-visible, or test-verifiable outcome. - -**Demo / Verification Outcome**: Describe exactly how someone can verify this phase is complete without inspecting implementation details. - -**Skills To Load**: - -| Skill | Why This Phase Needs It | -| -------------- | ----------------------- | -| `` | `` | - -**Likely Areas**: - -Use exact file paths only when they are durable and important. Prefer directories or modules when exact files may change. - -- `src/...` -- `tests/...` - -**Constraints**: - -List the durable constraints this phase MUST respect. - -- Constraint 1 -- Constraint 2 - -**Implementation Notes**: - -Provide enough implementation context that a subagent can start work without rediscovering scope. Do NOT invent product decisions that are absent from the PRD. - -- Note 1 -- Note 2 - -**Acceptance Criteria**: - -Each acceptance criterion MUST reference at least one PRD user story, functional requirement, or non-functional requirement unless the criterion is purely functional and no NFR applies. - -| ID | Acceptance Criterion | User Story ID(s) | Functional Requirement ID(s) | Non-Functional Requirement ID(s) | -| ------ | ------------------------------------------------------------ | ---------------- | ---------------------------- | -------------------------------- | -| AC-004 | Given , when , then . | US-001 | FR-001 | NFR-001 | -| AC-005 | Given , when , then . | US-001 | FR-002 | NFR-002 | -| AC-006 | can . | US-001 | FR-001, FR-002 | NFR-001 | - -**Testing Plan**: - -Describe the public behaviours and seams that MUST be tested for this phase. - | Test Level | Required Coverage | | --------------------- | ----------------- | | Unit | | From 8c29a7638793a427ce56df75a8d4621b97ff03b1 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter Date: Sun, 10 May 2026 19:53:40 +0100 Subject: [PATCH 3/5] Reduce Propulsion skill token usage --- skills/brainstorm/SKILL.md | 8 +-- skills/brainstorm/references/prd-template.md | 36 +++++------ skills/commit/SKILL.md | 6 +- skills/commit/references/workflow.md | 9 +-- skills/debug/SKILL.md | 12 ++-- .../debug/references/bug-feedback-prompt.md | 18 +++--- .../debug/references/bug-reviewer-prompt.md | 25 ++++---- skills/debug/references/bug-worker-prompt.md | 20 +++--- skills/debug/references/debug-template.md | 30 +++++---- skills/debug/references/investigation-loop.md | 18 +++--- skills/execute/SKILL.md | 10 +-- skills/execute/references/reviewer-prompt.md | 34 +++++------ .../references/worker-feedback-prompt.md | 14 ++--- skills/execute/references/worker-prompt.md | 6 +- skills/init-project/SKILL.md | 10 +-- skills/init-project/references/examples.md | 12 ++-- skills/init-project/references/process.md | 26 ++++---- skills/interrogate/SKILL.md | 11 ++-- .../references/interrogate-protocol.md | 20 +++--- skills/plan/SKILL.md | 10 +-- .../plan/references/plan-reviewer-prompt.md | 36 +++++------ skills/plan/references/plan-template.md | 28 ++++----- skills/pr/SKILL.md | 10 +-- skills/pr/references/workflow.md | 14 ++--- skills/review/SKILL.md | 4 +- skills/review/references/issue-schema.md | 8 +-- skills/review/references/mode-selection.md | 8 +-- skills/review/references/report-format.md | 30 ++------- skills/review/references/review-axes.md | 22 +++---- skills/review/references/reviewer-prompt.md | 22 ++++--- skills/review/references/validation-rubric.md | 16 +++-- skills/review/references/validator-prompt.md | 4 +- skills/tdd/SKILL.md | 8 +-- skills/tdd/references/refactor-candidates.md | 52 ++++------------ skills/tdd/references/testing-patterns.md | 61 ++++--------------- skills/write-skill/SKILL.md | 10 +-- skills/write-skill/assets/skill-template.md | 26 ++++---- skills/write-skill/references/checklist.md | 16 ++--- 38 files changed, 300 insertions(+), 410 deletions(-) diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index 19e75b3..5cf86f9 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -5,7 +5,7 @@ description: Create an approved PRD through repo inspection and interrogation. U # Brainstorm -Turn vague feature, UX, API, product-scope, or requirements work into an approved PRD. +Turn feature, UX, API, product-scope, or requirements work into an approved PRD. ## Prerequisites @@ -18,7 +18,7 @@ ALL prerequisites MUST be satisfied BEFORE following this skill. Follow these steps IN ORDER. Do NOT skip steps. 1. Load `interrogate` skill and interview the user about their request. -2. Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` using the template in [references/prd-template.md](references/prd-template.md). +2. Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` from [references/prd-template.md](references/prd-template.md). 3. Maliciously sanity-check `prd.md` against the conversation and add any missing decisions, facts, constraints, behaviours, or success criteria. 4. Ask the user to review and approve `prd.md`. 5. After explicit approval, enter the `plan` skill. @@ -27,9 +27,9 @@ Follow these steps IN ORDER. Do NOT skip steps. These rules are MANDATORY. -- ALWAYS use `interrogate` skill to reach a shared understanding BEFORE writing the PRD. +- ALWAYS use `interrogate` skill to reach shared understanding BEFORE writing the PRD. - ALWAYS use the PRD template for structure and section order. -- MUST keep the PRD product-facing while recording durable implementation and testing decisions. +- MUST keep the PRD product-facing and record durable implementation and testing decisions. - ENSURE the PRD includes ALL relevant decisions, even if they seem obvious or minor. - USE supporting documents such as `docs/propulsion/.../diagrams.md` if needed. - If you cannot write files, STOP, ask the user to enable write mode before continuing the PRD. diff --git a/skills/brainstorm/references/prd-template.md b/skills/brainstorm/references/prd-template.md index fe8aedf..9835b02 100644 --- a/skills/brainstorm/references/prd-template.md +++ b/skills/brainstorm/references/prd-template.md @@ -15,34 +15,29 @@ Describe the proposed behaviour end-to-end from the user's perspective. ## Goals -- Goal 1 -- Goal 2 +- Goal ## Non-Goals -- Explicit non-goal 1 -- Explicit non-goal 2 +- Explicit non-goal ## User Stories | ID | User Story | | ------ | ---------------------------------------------------- | | US-001 | As a , I want , so that . | -| US-002 | As a , I want , so that . | ## Functional Requirements | ID | Requirement | | ------ | -------------------------------------------- | | FR-001 | When , the system must . | -| FR-002 | The system must when . | ## Non-Functional Requirements | ID | Category | Requirement | | ------- | ----------- | --------------------------------------------- | | NFR-001 | Performance | must complete within . | -| NFR-002 | Security | The system must . | ## Implementation Decisions @@ -52,9 +47,8 @@ Describe the proposed behaviour end-to-end from the user's perspective. ## Implementation Inputs -- External links or references to check out -- Business rules or constraints that must be respected -- References to tickets, docs, or other internal resources that are relevant to implementation +- External links, tickets, docs, or references +- Business rules or constraints ## Testing Decisions @@ -78,15 +72,15 @@ These rules are MANDATORY. - ALWAYS follow the template structure and section order exactly as specified. - MUST use the following non-functional requirement categories: - - Performance: Response times, throughput, and resource utilisation under normal and peak loads. - - Reliability: System availability, fault tolerance, and error recovery capabilities. - - Security: Data protection, authentication, authorisation, and compliance with relevant standards. - - Usability: User experience, accessibility, and ease of use across different user groups. - - Scalability: Ability to handle increased load and growth in users or data volume. - - Maintainability: Code quality, documentation, and ease of future modifications. - - Compatibility: Cross-platform support, browser compatibility, and integration capabilities. - - Portability: Ability to deploy across different environments and infrastructure. - - Compliance: Adherence to industry standards, regulations, and organisational policies. - - Monitoring: Observability, logging, and alerting capabilities for operational support. -- MUST ensure there's a LONG and EXTENSIVE list of user stories, functional requirements, and non-functional requirements to cover all aspects of the feature. + - Performance: response times, throughput, resource use. + - Reliability: availability, fault tolerance, recovery. + - Security: data protection, authn/authz, compliance. + - Usability: UX, accessibility, ease of use. + - Scalability: growth in load, users, or data. + - Maintainability: code quality, docs, future changes. + - Compatibility: platform, browser, integration support. + - Portability: deployment across environments. + - Compliance: standards, regulations, policies. + - Monitoring: observability, logging, alerting. +- MUST ensure user stories, functional requirements, and non-functional requirements cover all feature aspects. - DO create supporting documents with mermaid diagrams, data models, or other relevant artefacts if they help clarify the feature or implementation. diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 5e6e873..666db3b 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -5,7 +5,7 @@ description: Create one safe local git commit from current changes. Use when ask # Commit -Create exactly one local git commit from safe current changes and report the result. +Create one safe local git commit and report the result. ## Prerequisites @@ -17,10 +17,10 @@ ALL prerequisites MUST be satisfied BEFORE following this skill. Follow these steps IN ORDER. Do NOT skip steps. -1. Inspect current state with `git status --short`, `git diff HEAD`, and `git branch --show-current`. +1. Inspect state with `git status --short`, `git diff HEAD`, and `git branch --show-current`. 2. Stage all local changes with `git add -A`, including untracked files. 3. Unstage every staged secret-like file matching [references/workflow.md](references/workflow.md). -4. Check staged changes after exclusions. If none remain, stop and output exactly `No changes to commit.` +4. Check staged changes after exclusions; if none remain, stop and output exactly `No changes to commit.` 5. Generate a one-line imperative commit subject from the staged diff. 6. Create exactly one local commit with that subject. 7. Run `git status --short` before the final response. diff --git a/skills/commit/references/workflow.md b/skills/commit/references/workflow.md index 34cdc77..937f71d 100644 --- a/skills/commit/references/workflow.md +++ b/skills/commit/references/workflow.md @@ -8,10 +8,9 @@ ## Secret-Like Exclusions -Never commit likely secret files. Always unstage staged files matching these patterns before committing: +Never commit likely secret files. Always unstage these patterns before committing: - `.env` -- `.env.*` - `*.pem` - `*.key` - `*.p12` @@ -24,12 +23,10 @@ Never commit likely secret files. Always unstage staged files matching these pat ## Commit Message -Use a normal imperative commit subject with this format: +Use a normal imperative commit subject: - one line only -- short descriptive subject line -- imperative mood -- normal natural wording +- short, descriptive, imperative, natural wording - no trailing punctuation ## No Committable Changes Output diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 674abd5..cc663dc 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -5,7 +5,7 @@ description: Handle concrete failures through intake, diagnosis, one-hypothesis # Debug -Diagnose concrete failures before dispatching one evidence-backed fix loop. +Diagnose concrete failures before one evidence-backed fix loop. ## Prerequisites @@ -19,15 +19,15 @@ ALL prerequisites MUST be satisfied BEFORE following this skill. Follow these steps IN ORDER. Do NOT skip steps. 1. Create or resume `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` from [references/debug-template.md](references/debug-template.md) before diagnosis work. -2. Record report provenance, expected behaviour, actual behaviour, impact, environment, reproduction, prior attempts, and open blockers in `debug.md`. +2. Record provenance, expected and actual behaviour, impact, environment, reproduction, prior attempts, and blockers in `debug.md`. 3. Load `interrogate` ONLY when missing user-answerable intake blocks expected behaviour, reproduction, impact, or environment; record answers and resolved decisions in `debug.md`. -4. Explore only the relevant code, tests, logs, recent changes, ownership, and likely boundaries; record facts and intentional limits in `debug.md`. +4. Explore only relevant code, tests, logs, recent changes, ownership, and likely boundaries; record facts and limits in `debug.md`. 5. Use [references/investigation-loop.md](references/investigation-loop.md) to reproduce, read the full error, reduce, compare working examples, isolate the first bad boundary, and test one diagnosis hypothesis at a time. 6. Gate fix dispatch until `debug.md` has grounded diagnosis evidence, the first bad state or divergence, fix constraints, a falsifier, and one chosen fix hypothesis. 7. Dispatch one fresh bug-worker with [references/bug-worker-prompt.md](references/bug-worker-prompt.md), then dispatch one fresh reviewer with [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md). -8. If review rejects the fix, return findings to the active worker with [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md) while the diagnosis still holds. +8. If review rejects the fix and diagnosis still holds, return findings to the active worker with [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md). 9. If verification, review, or new evidence contradicts the diagnosis, reset to investigation and record the contradicted evidence before any new fix attempt. -10. After 3 failed fix loops, reassess architecture and patterns, record the reassessment, then escalate to the user with evidence and next options. +10. After 3 failed fix loops, reassess architecture and patterns, record it, then escalate with evidence and next options. 11. Close only when fixed and verified, blocked by missing intake, no-repro after documented attempts, or escalated after the 3-loop reassessment path. ## Rules @@ -37,7 +37,7 @@ These rules are MANDATORY. - MUST keep `debug.md` current from entry through closure. - MUST diagnose before fixing; NEVER make permanent production-code edits in the controller stage. - MUST use `interrogate` only for missing user-answerable intake, not repo facts the agent can inspect. -- MUST reset instead of pushing through when evidence contradicts the diagnosis or chosen fix hypothesis. +- MUST reset when evidence contradicts the diagnosis or chosen fix hypothesis. - EVERY fix loop MUST target one chosen fix hypothesis and start with a failing regression test unless `tdd` declares no valuable test. - MUST record failed hypotheses, blocked/no-repro status, rejected reviews, resets, failed loops, verification, escalation, and closure. diff --git a/skills/debug/references/bug-feedback-prompt.md b/skills/debug/references/bug-feedback-prompt.md index dbed73a..ab042f6 100644 --- a/skills/debug/references/bug-feedback-prompt.md +++ b/skills/debug/references/bug-feedback-prompt.md @@ -5,7 +5,7 @@ Use this template when returning reviewer findings to the active bug-worker duri ````markdown **You are a subagent completing work in the Propulsion workflow.** -Your bug-fix attempt was reviewed independently under the `debug` skill. Treat the review as technical claims to verify, not instructions to obey blindly. +Your bug-fix attempt was independently reviewed. Treat review items as technical claims to verify. ## Review Report @@ -15,14 +15,14 @@ Your bug-fix attempt was reviewed independently under the `debug` skill. Treat t Follow these steps IN ORDER. Do NOT skip steps. -1. Read the full review report, current `debug.md`, and active diff. +1. Read the review report, current `debug.md`, and active diff. 2. Triage every reviewer finding as `valid`, `invalid`, or `unclear` before changing code. 3. If any finding is `unclear`, STOP and report `Status: unclear` with the missing evidence; do not change code. -4. Confirm every `valid` finding fits the active chosen fix hypothesis and does not require a new hypothesis. -5. If any valid finding or new evidence contradicts the diagnosis, chosen hypothesis, or fix constraints, STOP, update `debug.md`, and reset back to diagnosis. -6. For each valid in-scope finding, make the minimal correction within the active fix hypothesis only. -7. Keep the regression-test-first requirement intact for any additional code change; if no new test is valuable, record the `tdd` rationale and fallback proof. -8. Re-run the relevant checks and update `debug.md` with finding triage, code changes, verification outcome, and diagnosis status. +4. Confirm each `valid` finding fits the active hypothesis and does not require a new one. +5. If a valid finding or new evidence contradicts diagnosis, hypothesis, or constraints, STOP, update `debug.md`, and reset to diagnosis. +6. For each valid in-scope finding, make the minimal correction within the active hypothesis only. +7. Preserve regression-test-first for any code change; if no new test is valuable, record the `tdd` rationale and fallback proof. +8. Re-run relevant checks and update `debug.md` with triage, code changes, verification, and diagnosis status. 9. Return an implementation report in the exact format defined below. ## Output @@ -67,8 +67,8 @@ These rules are MANDATORY. - Preserve the diagnosis reset and one-hypothesis discipline. - Triage every finding before changing code. - Do not continue coding once the diagnosis is contradicted. -- Preserve the one-hypothesis, one-fix-loop discipline. -- Do not start a second fix hypothesis inside feedback handling; if a finding requires one, update `debug.md` and reset back to diagnosis. +- Preserve one-hypothesis, one-fix-loop discipline. +- Do not start a second fix hypothesis inside feedback handling; if one is required, update `debug.md` and reset to diagnosis. - Do not broaden the active fix beyond reviewer findings that fit the chosen fix hypothesis. - Update `debug.md` before handing control back to `debug`. - MUST return exactly one `Status:` field with `done`, `blocked`, or `unclear`. diff --git a/skills/debug/references/bug-reviewer-prompt.md b/skills/debug/references/bug-reviewer-prompt.md index 3944ec1..7efdfea 100644 --- a/skills/debug/references/bug-reviewer-prompt.md +++ b/skills/debug/references/bug-reviewer-prompt.md @@ -13,18 +13,18 @@ You are a sceptical implementation reviewer for one bug-fix attempt under the `d ## Implementation Report -This is the full self-review implementation report submitted by the bug-worker. **Do not trust it blindly, be sceptical and verify all claims yourself.** +This is the bug-worker report. **Treat it as context, not proof; verify every claim.** ## Review Focus -- Confirm the diagnosis gate was satisfied before any production-code change and that it still explains the bug. -- Reject if any required diagnosis evidence is missing: exact symptom, reduced reproduction or flaky classification, full error reading / error-reading conclusion, recent-change conclusion, applicable working example or explicit N/A, boundary tracing, first bad boundary or divergence / first-bad-divergence, fix constraints, chosen fix hypothesis, fail-then-pass regression proof, or reset evidence from prior failed loops. -- Confirm the regression-test-first requirement was followed. -- Confirm the fix matches the chosen fix hypothesis and fix constraints in `debug.md`. -- Confirm verification is sufficient for the reported bug behaviour, not just adjacent symptoms. -- If the implementation weakens the diagnosis or fails verification, require a reset back to diagnosis. +- Diagnosis gate was satisfied before production-code changes and still explains the bug. +- Reject missing required evidence: exact symptom, reduced repro/flaky classification, full error reading/conclusion, recent-change conclusion, working example or explicit N/A, boundary tracing, first bad boundary/divergence, fix constraints, chosen hypothesis, fail-then-pass proof, or prior-loop reset evidence. +- Regression-test-first requirement was followed. +- Fix matches the chosen hypothesis and constraints in `debug.md`. +- Verification proves the reported bug behaviour, not only adjacent symptoms. +- If the implementation weakens diagnosis or fails verification, require reset to diagnosis. ## Instructions @@ -33,10 +33,10 @@ Follow these steps IN ORDER. Do NOT skip steps. 1. Read the current `debug.md` and implementation report in full. 2. Inspect the real code, tests, and diff yourself; do not trust the worker report. 3. Verify the diagnosis gate was complete before the fix and that current evidence has not contradicted it. -4. Verify the regression test failed first for the expected bug reason, then passed after the fix; `debug.md` must show both results. If no test was written, verify `tdd` explicitly declared no valuable test and the fallback proof is sufficient. -5. Verify the change stays within the chosen fix hypothesis and fix constraints, with no symptom-only masking or unexplained evidence hidden by the patch. -6. Verify the checks run are sufficient for the reported bug behaviour and affected boundaries. -7. Return approval only if the diagnosis gate, chosen hypothesis fit, regression-test-first proof or accepted no-test rationale, diagnosis status, and verification all hold. +4. Verify the test failed first for the expected bug reason, then passed; `debug.md` must show both. If no test, verify `tdd` declared no valuable test and fallback proof is sufficient. +5. Verify the change stays within the chosen hypothesis/constraints, with no symptom masking or unexplained evidence hidden by the patch. +6. Verify checks cover the reported behaviour and affected boundaries. +7. Approve only if gate, hypothesis fit, regression-first proof or accepted no-test rationale, diagnosis status, and verification all hold. 8. If anything fails, reject the attempt and state whether `debug` must reset back to diagnosis. ## Output @@ -87,8 +87,7 @@ Use this exact format for your output. These rules are MANDATORY. - Treat the diagnosis gate as required, not advisory. -- Reject speculative or symptom-only fixes. -- Reject missing root-cause evidence, missing fail-then-pass proof or accepted no-test rationale, changes outside the chosen fix hypothesis, or permanent code changes made outside the bug-worker subagent. +- Reject speculative or symptom-only fixes; missing root-cause evidence; missing fail-then-pass proof or accepted no-test rationale; changes outside the chosen hypothesis; or permanent code changes outside the bug-worker subagent. - Call out missing verification or contradictory evidence explicitly. - MUST return exactly one `Status:` line with either `approved` or `rejected`. - If `Status: rejected`, MUST include at least one finding. diff --git a/skills/debug/references/bug-worker-prompt.md b/skills/debug/references/bug-worker-prompt.md index b98c6bc..627fe2a 100644 --- a/skills/debug/references/bug-worker-prompt.md +++ b/skills/debug/references/bug-worker-prompt.md @@ -5,7 +5,7 @@ Use this template when starting a fresh bug-worker subagent for one bug-fix loop ````markdown **You are a subagent completing work in the Propulsion workflow.** -You are a senior software engineer implementing exactly one diagnosis-gated bug-fix attempt under the `debug` skill. +Implement exactly one diagnosis-gated bug-fix attempt under the `debug` skill. ## Bug Context @@ -17,14 +17,14 @@ You are a senior software engineer implementing exactly one diagnosis-gated bug- Follow these steps IN ORDER. Do NOT skip steps. -1. Review the bug context and ask questions if the diagnosis gate, chosen hypothesis, fix constraints, or repo state is unclear. Do not guess. -2. Verify the full diagnosis gate in `debug.md`: exact symptom, reduced reproduction or flaky classification, full error reading, recent-change conclusion, applicable working example or explicit N/A, boundary tracing, first bad boundary or divergence, fix constraints, chosen fix hypothesis, falsifier, and reset evidence from prior loops if any. -3. If the diagnosis gate is incomplete, contradicted, or not tied to the chosen fix hypothesis, STOP and report `Status: blocked` or `Status: unclear`; do not edit production code. +1. Review context; ask if the diagnosis gate, chosen hypothesis, fix constraints, or repo state is unclear. +2. Verify `debug.md` has: exact symptom, reduced repro or flaky classification, full error reading, recent-change conclusion, working example or explicit N/A, boundary tracing, first bad boundary/divergence, fix constraints, chosen fix hypothesis, falsifier, and prior-loop reset evidence if any. +3. If the gate is incomplete, contradicted, or not tied to the hypothesis, STOP and report `Status: blocked` or `Status: unclear`; do not edit production code. 4. Load the `tdd` skill NOW and follow it before any production-code change. -5. Add or update the smallest valuable regression test first and verify it fails for the expected bug reason. If `tdd` declares no valuable test, record the no-test rationale and strongest fallback verification in `debug.md` before fixing. -6. Implement one minimal fix attempt only for the chosen fix hypothesis and within the fix constraints. -7. Re-run the regression proof and relevant verification checks. -8. Update `debug.md` with the diagnosis-gate verification, regression-test-first evidence or no-test rationale, fix attempt, verification result, and any contradictory evidence. +5. Add/update the smallest valuable regression test first and verify the expected failure. If `tdd` declares no valuable test, record the rationale plus strongest fallback verification in `debug.md` before fixing. +6. Implement one minimal fix for the chosen hypothesis within constraints. +7. Re-run regression proof and relevant checks. +8. Update `debug.md` with gate verification, regression-first evidence or no-test rationale, fix attempt, verification, and contradictions. 9. Return an implementation report in the exact format defined below. ## Output @@ -63,8 +63,8 @@ These rules are MANDATORY. - ALWAYS load and follow the `tdd` skill. - ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY. - Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise. -- NO PRODUCTION CODE before a failing regression test unless `tdd` declares no valuable test and `debug.md` records the rationale plus fallback verification. -- Only bug-worker subagents make permanent code changes; the debug controller may make temporary diagnostic edits only when they are recorded and reverted before fix handoff. +- NO PRODUCTION CODE before a failing regression test unless `tdd` declares no valuable test and `debug.md` records rationale plus fallback verification. +- Only bug-worker subagents make permanent code changes; debug controller diagnostic edits must be recorded and reverted before fix handoff. - Work only on the chosen fix hypothesis for this loop; do not broaden or replace it. - Make one minimal fix attempt only; do not stack speculative fixes. - If evidence contradicts the diagnosis or chosen hypothesis, STOP, update `debug.md`, and reset back to diagnosis. diff --git a/skills/debug/references/debug-template.md b/skills/debug/references/debug-template.md index ce612d8..baff84e 100644 --- a/skills/debug/references/debug-template.md +++ b/skills/debug/references/debug-template.md @@ -7,13 +7,13 @@ Create or resume one living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` dos ## Intake -- Source and timestamp: `` +- Source/time: `` - Original report: `` - Exact symptom: `` - Expected behaviour: `` - Actual behaviour: `` - Impact: `` -- Environment reported: `` +- Environment: `` - Questions answered: `` - Open blockers: `` @@ -30,23 +30,23 @@ Create or resume one living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` dos - Status: `` - Exact command/path: `` - Expected vs actual: `` -- Full output location: `` +- Full output: `` - Reduced repro: `` - No-repro/blocking rationale: `` ## Full Error Reading -- Complete error evidence: `` +- Complete error: `` - First meaningful frame/signal: `` - Surrounding context: `` -- Conclusion: `` +- Conclusion: `` ## Environment And Recent Changes - Revision/build: `` -- Runtime/platform/config/data: `` -- Working tree/staged diff: `` -- Recent commits/release delta: `` +- Runtime/config/data: `` +- Worktree/staged diff: `` +- Recent delta: `` - Change conclusion: `` ## Reduction And Comparison @@ -54,13 +54,13 @@ Create or resume one living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` dos - Smallest failing case: `` - Variables removed/controlled: `` - Working example: `` -- Broken vs working differences: `` +- Broken vs working diff: `` - First observed divergence: `` ## Boundary Tracing - Boundary map: `` -- Ingress/egress observations: `` +- Handoff observations: `` - Config/data/state propagation: `` - First bad boundary: `` @@ -74,7 +74,6 @@ Create or resume one living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` dos - E1. `` - E2. `` -- E3. `` ## Hypotheses And Experiments @@ -86,7 +85,7 @@ Create or resume one living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` dos - Actual result: `` - Falsifier: `` - Conclusion: `` -- H2. `` +- H2. `` ## Diagnosis Gate @@ -128,7 +127,7 @@ Create or resume one living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` dos ## Closure - Final status: `` -- User-visible resolution: `` +- Resolution: `` - Closure evidence: `` - Follow-ups: `` ``` @@ -140,8 +139,7 @@ Create or resume one living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` dos - If expected behaviour, reproduction, or environment is unknowable, record the blocker and do not dispatch a fix. - Ground the diagnosis gate before any production-code change or fix dispatch. - Use one hypothesis, one experiment, and one fix at a time; record expected experiment results before running them. -- Record flaky, no-repro, regression-window, performance, environment/config, data-dependent, concurrency, and multi-component evidence using the same sections. -- Record temporary diagnostic edits with file, purpose, tag/comment marker when relevant, observation, and revert status. -- Revert temporary diagnostic edits before fix handoff. +- Use the same sections for flaky, no-repro, regression-window, performance, environment/config, data-dependent, concurrency, and multi-component evidence. +- Record diagnostic edits with file, purpose, marker when relevant, observation, and revert status; revert them before fix handoff. - Preserve failed hypotheses, contradicted evidence, rejected reviews, reset reasons, failed fix loops, and escalations. - After 3 failed fix loops, reassess architecture and patterns before escalating. diff --git a/skills/debug/references/investigation-loop.md b/skills/debug/references/investigation-loop.md index 7703c60..0a0b2a9 100644 --- a/skills/debug/references/investigation-loop.md +++ b/skills/debug/references/investigation-loop.md @@ -1,12 +1,12 @@ # Investigation Loop -Use this loop to keep `debug.md` evidence-first and to stop fixes before root cause is grounded. +Use this loop to keep `debug.md` evidence-first and block fixes before root cause is grounded. ## Loop 1. Capture the feedback signal. -- Record the exact symptom: failing command, assertion, crash, wrong output, visible behaviour, alert, or metric. +- Record the exact symptom: failing command, assertion, crash, wrong output, visible behaviour, alert, metric. - Record expected versus actual behaviour and the user impact. - Freeze relevant environment facts: revision, runtime, platform, flags, config, inputs, time/locale, dataset, tenant, CI/prod scope. @@ -14,7 +14,7 @@ Use this loop to keep `debug.md` evidence-first and to stop fixes before root ca - Reproduce before theorising using one command, script, URL, or manual path. - If it will not reproduce, record no-repro attempts, environment gaps, and the next needed signal before blocking or asking. -- For flaky failures, prove pass/fail variation, capture run counts, freeze seed/time/order where possible, and record what changes between runs. +- For flaky failures, prove pass/fail variation, capture run counts, freeze seed/time/order where possible, and record changing factors. 3. Read the failure fully. @@ -23,19 +23,19 @@ Use this loop to keep `debug.md` evidence-first and to stop fixes before root ca 4. Scan recent changes. -- Check working tree diff, staged diff, recent commits, dependencies, config, environment, CI, runtime drift, and release delta before broad code reading. +- Check working tree diff, staged diff, recent commits, dependencies, config, environment, CI, runtime drift, release delta before broad code reading. - If a good/bad window exists, record the smallest credible window and isolate it before guessing. 5. Reduce the case. - Remove fixtures, services, flags, data, timing, and setup while preserving the same symptom. - If the symptom changes, record that the problem changed and reset the reduction. -- For performance/resource failures, reduce to the threshold and boundary where the cost first diverges from a good baseline. +- For performance/resource failures, reduce to the threshold and boundary where cost first diverges from a good baseline. - For data-dependent failures, shrink to the smallest input, fixture, stored state, or tenant dataset that still fails. 6. Compare with working evidence. -- Compare against a passing test, adjacent feature, prior release, reference implementation, known-good trace, or good environment. +- Compare against a passing test, adjacent feature, prior release, reference implementation, known-good trace, good environment. - For environment/config failures, compare runtime, flags, env, and config propagation at each boundary. - Record the first meaningful broken-versus-working difference. @@ -49,17 +49,17 @@ Use this loop to keep `debug.md` evidence-first and to stop fixes before root ca - Keep one current best hypothesis plus the strongest alternative and unexplained evidence. - Define the falsifier and one discriminating experiment before running it. -- Prefer existing logs, traces, dumps, breakpoints, logpoints, watchpoints, and debugger inspection before mutating code. +- Prefer logs, traces, dumps, breakpoints, logpoints, watchpoints, and debugger inspection before mutating code. 9. Experiment once. - Run one experiment at a time and record expected result, actual result, and conclusion. -- Temporary diagnostic edits are allowed only for investigation; record file, purpose, tag/comment marker when relevant, observation, and revert status in `debug.md`. +- Temporary diagnostic edits are allowed only for investigation; record file, purpose, tag/comment marker when relevant, observation, revert status in `debug.md`. - Revert temporary diagnostic edits before fix handoff. 10. Diagnose and gate the fix. -- Ground the diagnosis only when evidence explains the earliest bad state or divergence, not just the late symptom. +- Ground the diagnosis only when evidence explains the earliest bad state or divergence, not just late symptoms. - Record root cause, falsifier, fix constraints, and one chosen fix hypothesis. - Dispatch one fix at a time; if evidence no longer fits, reset diagnosis instead of pushing through. diff --git a/skills/execute/SKILL.md b/skills/execute/SKILL.md index 6d24a6b..6396013 100644 --- a/skills/execute/SKILL.md +++ b/skills/execute/SKILL.md @@ -18,13 +18,13 @@ ALL prerequisites MUST be satisfied BEFORE following this skill. Follow these steps IN ORDER. Do NOT skip steps. 1. Review and select the first incomplete phase in `plan.md`. -2. Start a fresh worker subagent with the prompt in [references/worker-prompt.md](references/worker-prompt.md). +2. Start a fresh worker subagent with [references/worker-prompt.md](references/worker-prompt.md). 3. Wait for the worker to finish and handle the status: - If `Status: unclear`, provide additional context or clarification. - If `Status: blocked`, triage the blocker and resolve it. - If you cannot resolve `unclear` or `blocked` from the plan, codebase, or tools, escalate to the user. - If `Status: done`, continue to review. -4. Start a fresh reviewer subagent with the prompt in [references/reviewer-prompt.md](references/reviewer-prompt.md). +4. Start a fresh reviewer subagent with [references/reviewer-prompt.md](references/reviewer-prompt.md). 5. Wait for the reviewer to finish and handle the status: - If `Status: approved`, mark the current phase complete in `plan.md`. - If `Status: rejected`, send the findings back to the same worker subagent with the prompt in [references/worker-feedback-prompt.md](references/worker-feedback-prompt.md). @@ -39,11 +39,11 @@ Follow these steps IN ORDER. Do NOT skip steps. These rules are MANDATORY. - NEVER implement a phase without a worker subagent. -- ALWAYS user a fresh reviewer subagent for every review. -- NEVER resolve `Status: unclear` or `Status: blocked` by guessing; if the information is not in the plan, codebase, or tools, escalate to the user for resolution. +- ALWAYS use a fresh reviewer subagent for every review. +- NEVER resolve `Status: unclear` or `Status: blocked` by guessing; if the answer is not in the plan, codebase, or tools, escalate to the user. - ALWAYS update `plan.md` checkboxes after each successful implementation-review cycle. - MUST infer and run relevant repo-wide checks before claiming completion. -- NEVER implement user feedback directly in `execute`, instead: +- NEVER implement user feedback directly in `execute`; instead: - Loop back to `brainstorm` to update the PRD. - Move to `plan` to create or update a phase if needed. - Return to `execute` for implementation. diff --git a/skills/execute/references/reviewer-prompt.md b/skills/execute/references/reviewer-prompt.md index b3e516f..3903a8c 100644 --- a/skills/execute/references/reviewer-prompt.md +++ b/skills/execute/references/reviewer-prompt.md @@ -7,7 +7,7 @@ Use this template when starting a fresh reviewer subagent in the `execute` skill You are an implementation reviewer. -Review the completed phase like a senior engineer: verify the real work product against the plan, acceptance criteria, code quality, security, tests, and regression risk. +Review the completed phase like a senior engineer: verify real work against the plan, acceptance criteria, code quality, security, tests, and regression risk. ## Task Context @@ -16,25 +16,25 @@ Review the completed phase like a senior engineer: verify the real work product ## Implementation Report -This is the full implementation report submitted by the worker. **Treat it as context, not proof. Independently verify claims against `plan.md`, changed files, the current diff, and check output.** +This is the worker report. **Treat it as context, not proof; verify against `plan.md`, changed files, diff, and check output.** ## Review Criteria -| Category | What to verify | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Plan Alignment | The implementation matches the current phase goal, demo / verification outcome, likely areas, constraints, and implementation notes without drift. | -| Acceptance Criteria | Every current-phase acceptance criterion is evaluated by ID as `met`, `not met`, or `unclear` with evidence from the actual implementation. | -| Functional Correctness | Changed code, tooling, architecture, or behaviour satisfy the phase contract without broken logic, contradictions, or incomplete handling. | -| Tests / Verification | Relevant tests or checks were run where feasible, missing verification is reported, and tests validate observable behaviour without brittle coupling to source shape, private helpers, or incidental implementation details. | -| Maintainability / Refactoring | The work is clear, cohesive, appropriately simple, DRY, SOLID, YAGNI-aligned, and free of avoidable complexity or missed refactoring opportunities. | -| Security / Trust Boundaries | Inputs, permissions, secrets, file access, external calls, prompt boundaries, and other trust boundaries remain safe for the changed scope. | -| Performance / Reliability | The implementation avoids avoidable latency, resource waste, brittle failure modes, race conditions, and unreliable workflow states. | -| Integration / Regression Risk | Surrounding workflows, APIs, prompts, feedback loops, conventions, and existing behaviours remain compatible. | -| Output Usefulness | Rejections include actionable, evidence-backed findings a worker can verify or challenge technically. | +| Category | Verify | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Plan Alignment | Matches current phase goal, demo outcome, likely areas, constraints, and implementation notes. | +| Acceptance Criteria | Every current-phase criterion is evaluated by ID as `met`, `not met`, or `unclear` with evidence. | +| Functional Correctness | Changed code/tooling/architecture/behaviour satisfies the phase contract without broken logic or incomplete handling. | +| Tests / Verification | Relevant checks ran where feasible; missing verification is reported; tests prove behaviour without brittle coupling to internals. | +| Maintainability / Refactoring | Work is clear, cohesive, simple, DRY, SOLID, YAGNI-aligned, and free of avoidable complexity. | +| Security / Trust Boundaries | Inputs, permissions, secrets, file access, external calls, prompt boundaries, and trust boundaries remain safe. | +| Performance / Reliability | Avoids avoidable latency, resource waste, brittle failures, races, and unreliable workflow states. | +| Integration / Regression Risk | Surrounding workflows, APIs, prompts, feedback loops, conventions, and behaviours remain compatible. | +| Output Usefulness | Rejections are actionable and evidence-backed. | -Flag only real issues supported by evidence from the plan, diff, files, checks, prompts, or documented workflow rules. +Flag only real issues supported by plan, diff, files, checks, prompts, or workflow rules. ## Instructions @@ -42,10 +42,10 @@ Follow these steps IN ORDER. Do NOT skip steps. 1. Read the current phase directly from `plan.md`. 2. Review the worker report as context, not proof. -3. Inspect the real implementation, including relevant changed files and the current diff. +3. Inspect the real implementation, relevant changed files, and diff. 4. Load relevant skills when needed to validate the produced work against skill-specific standards. 5. Run relevant tests or checks where feasible; if verification cannot be performed, report that clearly. -6. Use the review criteria table to evaluate the work product and every current-phase acceptance criterion by ID. +6. Use the criteria table to evaluate the work and every current-phase acceptance criterion by ID. 7. Report real issues as findings using `critical`, `high`, `medium`, `low`, or `nitpick`. 8. Return the implementation review report in the exact format below. @@ -92,7 +92,7 @@ These rules are MANDATORY. - DO NOT approve tests that assert implementation details in a way that would fail under behaviour-preserving refactors. - INCLUDE at least one actionable finding when using `rejected`. - ORDER findings by severity, highest first, with `nitpick` findings last. -- ENSURE findings are evidence-based, actionable, and specific enough for a worker to verify or challenge technically. +- ENSURE findings are evidence-based, actionable, and specific enough to verify or challenge. - NEVER make code changes; review only. - ALWAYS follow the output structure and section order exactly as specified. diff --git a/skills/execute/references/worker-feedback-prompt.md b/skills/execute/references/worker-feedback-prompt.md index d892c92..3b497dc 100644 --- a/skills/execute/references/worker-feedback-prompt.md +++ b/skills/execute/references/worker-feedback-prompt.md @@ -5,7 +5,7 @@ Use this template when returning review findings to the active worker subagent i ````markdown **You are a subagent completing work in the Propulsion workflow.** -Your work has been reviewed. Verify each review finding as a technical claim against the real plan, codebase, diff, checks, and workflow rules. Fix valid findings, reject invalid findings with evidence, and escalate unclear findings. +Your work has been reviewed. Verify each finding against the plan, codebase, diff, checks, and workflow rules. Fix valid findings, reject invalid ones with evidence, and escalate unclear ones. ## Review Report @@ -17,12 +17,12 @@ Follow these steps IN ORDER. Do NOT skip steps. 1. Review the current phase details directly from `plan.md`. 2. Review the full implementation review report. -3. Inspect the relevant plan sections, changed files, current diff, checks, and codebase context needed to evaluate the review findings. +3. Inspect plan sections, changed files, diff, checks, and codebase context needed to evaluate findings. 4. Triage every review finding as `valid`, `invalid`, or `unclear` before making any code change. -5. If any finding remains `unclear` after investigation, STOP and return `Status: unclear` with the specific information needed to continue. -6. For every `invalid` finding, keep the implementation unchanged and prepare evidence-backed pushback. -7. For every `valid` finding, load the `tdd` skill, follow it, and make the minimal correct fix. -8. Load any additional recommended skills not already active or present in context when needed to validate or fix the reviewed work. +5. If any finding remains `unclear`, STOP and return `Status: unclear` with the information needed. +6. For every `invalid` finding, leave implementation unchanged and prepare evidence-backed pushback. +7. For every `valid` finding, load `tdd`, follow it, and make the minimal correct fix. +8. Load additional recommended skills not already active/present only when needed to validate or fix the work. 9. Verify the implementation works and conforms to the current phase in `plan.md`. 10. Re-evaluate every current-phase acceptance criterion by ID. 11. Return your implementation report in the exact format below. @@ -70,7 +70,7 @@ These rules are MANDATORY. - ALWAYS triage every review finding as `valid`, `invalid`, or `unclear` before changing code. - Status MUST be `unclear` if any finding cannot be triaged after inspecting the plan, codebase, diff, checks, and available evidence. - Status MUST be `blocked` if a valid finding cannot be fixed because of missing access, failing tooling, contradictory requirements, or another blocker. -- Status CAN ONLY be `done` when every finding is resolved, every valid finding is fixed, every invalid finding has evidence-backed pushback, and every acceptance criterion is re-evaluated. +- Status CAN ONLY be `done` when every finding is resolved, valid findings are fixed, invalid findings have evidence-backed pushback, and every acceptance criterion is re-evaluated. - DO NOT change code for invalid findings. - DO NOT make speculative changes beyond the current phase or review findings. - ALWAYS use the `tdd` skill to fix valid findings, loading it only when it is not already active or present in context. diff --git a/skills/execute/references/worker-prompt.md b/skills/execute/references/worker-prompt.md index 9f453e5..06c26b6 100644 --- a/skills/execute/references/worker-prompt.md +++ b/skills/execute/references/worker-prompt.md @@ -5,7 +5,7 @@ Use this template when starting a fresh worker subagent in the `execute` skill. ````markdown **You are a subagent completing work in the Propulsion workflow.** -You are a senior software engineer implementing the current phase of work defined below. +Implement the current phase defined below. ## Task Context @@ -16,9 +16,9 @@ You are a senior software engineer implementing the current phase of work define Follow these steps IN ORDER. Do NOT skip steps. -1. Review the current phase details in `plan.md`. +1. Review current phase details in `plan.md`. 2. Load any recommended skills for this phase immediately. -3. Gather additional context from the codebase, PRD, and any relevant tools as needed. +3. Gather needed context from the codebase, PRD, and tools. 4. Ask any clarifying questions if the requirements, scope, or repo state are unclear. 5. Load the `tdd` skill and follow it to implement the requirements. 6. Verify your implementation works and conforms to the plan. diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md index 42761b9..a43a2cc 100644 --- a/skills/init-project/SKILL.md +++ b/skills/init-project/SKILL.md @@ -5,17 +5,17 @@ description: Create or prune AGENTS.md into minimal global steering for agents. # Init Project -Create or prune `AGENTS.md` as a tiny global protocol, not a repository overview. +Create or prune `AGENTS.md` as tiny global protocol, not a repo overview. ## Instructions Follow these steps IN ORDER. Do NOT skip steps. -1. Launch a fresh explorer subagent to inspect the repository before editing: existing `AGENTS.md` files, package/tool configs, docs, scripts, and visible conventions that could make proposed rules discoverable. -2. Load the `interrogate` skill to gather global, non-discoverable instructions the repository cannot reveal, including human protocol, hidden operational landmines, environment gotchas, and mandatory verification timing. +1. Launch a fresh explorer subagent before editing to inspect existing `AGENTS.md` files, package/tool configs, docs, scripts, and visible conventions. +2. Load `interrogate` to gather global, non-discoverable instructions the repository cannot reveal, including human protocol, hidden landmines, environment gotchas, and verification timing. 3. Preserve or add the default correction rule near the top of `AGENTS.md`. 4. Apply the line admission test to every candidate rule: global, non-discoverable, and operationally important. -5. Challenge weak or bloated candidate instructions before keeping them; remove any rule that fails the admission test or belongs in code, config, docs, skills, or commands. +5. Challenge weak or bloated candidates before keeping them; remove rules that fail the admission test or belong in code, config, docs, skills, or commands. 6. Draft the smallest useful `AGENTS.md`, keeping always-followed rules near the top. 7. Handoff with the changed file path plus kept, removed, and challenged rule categories. @@ -25,7 +25,7 @@ These rules are MANDATORY. - MUST launch a fresh explorer subagent before creating, pruning, or rewriting `AGENTS.md`. - MUST use `interrogate` skill for human-only, repo-wide rules that repository inspection cannot discover. -- MUST keep only rules that pass all three admission checks: global, non-discoverable, operationally important. +- MUST keep only rules that pass all admission checks: global, non-discoverable, operationally important. - MUST challenge or remove vague, task-specific, discoverable, duplicated, or low-impact instructions. - MUST use this default correction rule: "- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`." - DO NOT include tech stack summaries, folder maps, command inventories, architecture recaps, or style rules already enforced by tooling. diff --git a/skills/init-project/references/examples.md b/skills/init-project/references/examples.md index b9faf1a..773775e 100644 --- a/skills/init-project/references/examples.md +++ b/skills/init-project/references/examples.md @@ -1,6 +1,6 @@ # AGENTS.md Examples -These examples show minimal protocol-style `AGENTS.md` files and pruning decisions. +Examples of minimal protocol-style `AGENTS.md` files and pruning decisions. ## Default Rule Only @@ -14,7 +14,7 @@ Use this when no repo-specific rule passes the admission test. ## Environment Gotcha -Keep invisible environment constraints that can cause repeated failures. +Keep invisible environment constraints causing repeated failures. ```markdown # AGENTS.md @@ -25,7 +25,7 @@ Keep invisible environment constraints that can cause repeated failures. ## Hidden Landmine -Keep repo-wide operational facts that code structure hides. +Keep repo-wide operational facts hidden by code structure. ```markdown # AGENTS.md @@ -51,7 +51,7 @@ Keep mandatory verification timing when the obligation or timing is not discover - After implementing changes run `bun run test` before handoff. ``` -Reason: this is not a command inventory; it defines mandatory per-change timing that scripts alone do not reveal. +Reason: this defines mandatory per-change timing that scripts alone do not reveal. Remove command inventories: @@ -59,7 +59,7 @@ Remove command inventories: - Run `bun test` for tests and `bun run lint` for linting. ``` -Reason: scripts and CI already document commands. Keep only a non-discoverable command caveat, such as a cache flag required to avoid false positives. +Reason: scripts and CI already document commands. Keep only non-discoverable caveats, such as a cache flag required to avoid false positives. Challenge vague preferences: @@ -67,7 +67,7 @@ Challenge vague preferences: - Write clean code and keep files organized. ``` -Reason: not operationally specific. Ask for a concrete repo-wide failure mode or delete it. +Reason: not operationally specific. Ask for a concrete repo-wide failure mode or delete. Relocate task-specific workflow: diff --git a/skills/init-project/references/process.md b/skills/init-project/references/process.md index 613d954..7249b91 100644 --- a/skills/init-project/references/process.md +++ b/skills/init-project/references/process.md @@ -1,28 +1,28 @@ # Minimal AGENTS.md Process -Use this workflow when creating, pruning, or updating `AGENTS.md` under the strict minimal-context policy. +Use when creating, pruning, or updating `AGENTS.md` under the strict minimal-context policy. ## 1. Inspect Before Editing -Launch a fresh explorer subagent to read enough repository evidence to avoid duplicating discoverable facts: +Launch a fresh explorer subagent to read enough evidence to avoid duplicating discoverable facts: -- Existing `AGENTS.md` files, including parent or nested files that may apply. +- Existing applicable `AGENTS.md` files, including parent or nested files. - Package manifests, task runners, Makefiles, build files, and test configs. - Formatter, linter, TypeScript, CI, and editor config. -- Docs that already describe setup, scripts, architecture, or conventions. +- Docs describing setup, scripts, architecture, or conventions. - Source layout and naming patterns when they answer a proposed rule. Do not add repository summaries. Inspection exists to identify what does not belong in `AGENTS.md`. ## 2. Ask For Invisible Rules -Use the existing `interrogate` skill to ask the user for rules the repository cannot reliably reveal. Focus on: +Use the existing `interrogate` skill to ask for rules the repository cannot reveal. Focus on: -- Human protocol that must persist across sessions. +- Human protocol persisting across sessions. - Hidden operational landmines, unsafe directories, or legacy coupling. - Environment quirks not encoded in config. - Repo-wide constraints not enforced by code, tests, lint, CI, or docs. -- Mandatory verification timing that applies to every change but is not reliably encoded in scripts, docs, or CI. +- Mandatory verification timing for every change when not encoded in scripts, docs, or CI. If the user gives candidate rules, classify them instead of accepting them uncritically. @@ -38,13 +38,13 @@ Do not keep older variants that prescribe loading a skill or editing the file af ## 4. Apply The Admission Test -Keep every non-default line only if all checks pass: +Keep non-default lines only if all checks pass: - Global: applies to every task or session in this repository. - Non-discoverable: an agent cannot reliably infer it from repository files, tooling, docs, or scripts. - Operationally important: missing it is likely to cause mistakes, wasted effort, unsafe edits, or broken workflow. -Mandatory per-change verification timing can pass the non-discoverable check when the obligation or handoff timing is not reliably encoded in tooling, scripts, docs, or CI. +Mandatory per-change verification timing can pass when the obligation or handoff timing is not encoded in tooling, scripts, docs, or CI. If any check fails, challenge the rule or remove it. @@ -52,21 +52,21 @@ If any check fails, challenge the rule or remove it. Push back on candidates that are: -- Discoverable from source, config, package files, or docs. +- Discoverable from source, config, packages, or docs. - Task-specific workflows that belong in a skill, command, issue, or PRD. - Style preferences enforced by formatter, linter, types, or tests. - Generic good advice that applies to all repositories. - Vague intent without operational consequence. -- Bloated multi-line explanations that can be compressed into one actionable rule. +- Multi-line explanations compressible into one actionable rule. -When challenging, explain the failed admission check and suggest the smaller replacement, a better home, or deletion. +When challenging, explain the failed admission check and suggest a smaller replacement, better home, or deletion. ## 6. Draft The Smallest Useful File Prefer a short protocol file: 1. Put the default correction rule first or near the top. -2. Put always-followed repo-wide rules immediately after it. +2. Put always-followed repo-wide rules after it. 3. Group only when grouping improves scanning; avoid section filler. 4. Keep only the final accepted rules, not the rationale. 5. If nothing repo-specific qualifies, leave a one-rule file. diff --git a/skills/interrogate/SKILL.md b/skills/interrogate/SKILL.md index 880374c..aab5402 100644 --- a/skills/interrogate/SKILL.md +++ b/skills/interrogate/SKILL.md @@ -5,17 +5,17 @@ description: Manage interrogation, intake, interviews, scope clarification, requ # Interrogate -Reach a shared understanding by exploring the project for context and interrogating the user one question at a time. +Reach shared understanding through project context and one-question-at-a-time user interrogation. ## Instructions Follow these steps IN ORDER. Do NOT skip steps. -1. Gather context by launching a fresh explorer subagent to inspect the project for facts relevant to the request. -2. Interrogate the user relentlessly about every aspect of the request until a shared understanding is reached. +1. Launch a fresh explorer subagent to inspect project facts relevant to the request. +2. Interrogate the user about every aspect of the request until shared understanding is reached. - Ask questions one at a time, provide your recommended answer first, then 2-3 viable alternatives. - Walk down each branch of the decision tree resolving dependencies between decisions. - - There are no limits on the number of questions; keep asking until a shared understanding is reached. + - Keep asking until shared understanding is reached. 3. Return a concise summary to the caller. ## Rules @@ -23,7 +23,8 @@ Follow these steps IN ORDER. Do NOT skip steps. These rules are MANDATORY. - MUST use explorer subagent for entry exploration. -- ALWAYS relentlessly interrogate the user until a shared understanding is reached. +- ALWAYS interrogate the user until shared understanding is reached. +- NEVER think "this is too many questions", it isn't. - DO NOT limit the number of questions; keep asking until EVERY blocking branch is closed. - MUST ask user exactly one question at a time, provide a recommended answer, then 2-3 viable alternatives. - ALWAYS check if a question can be answered by project inspection before asking. diff --git a/skills/interrogate/references/interrogate-protocol.md b/skills/interrogate/references/interrogate-protocol.md index 105c0c1..df9654b 100644 --- a/skills/interrogate/references/interrogate-protocol.md +++ b/skills/interrogate/references/interrogate-protocol.md @@ -1,14 +1,14 @@ # Interrogate Protocol -Use this protocol when a request needs missing information resolved before it can proceed safely. +Use when a request needs missing information resolved before safe progress. ## Entry Exploration -Launch a fresh explorer subagent to inspect available project context before asking the user anything. Use the user's request, the current workflow goal, and any facts needed to avoid asking questions the project can answer. Use those findings to seed the initial decision tree. +Launch a fresh explorer subagent before asking the user anything. Inspect project context needed to avoid answerable questions, then seed the initial decision tree. ## Decision Tree -Build an explicit decision tree before the first user question. Include every branch that could affect the answer or next action, especially: +Build an explicit decision tree before the first user question. Include branches that could affect the answer or next action, especially: - intended outcome and non-goals - user workflow, UX, API, CLI, or agent-facing behaviour @@ -18,17 +18,17 @@ Build an explicit decision tree before the first user question. Include every br - errors, edge cases, security, privacy, and performance constraints - tests, acceptance criteria, verification, and handoff expectations -Track each branch as open or closed. Work the highest-impact blocking branch first, then update the tree after every project finding or user answer. A branch is closed only when it is fully answered by project facts or answered by the user. +Track each branch as open or closed. Work the highest-impact blocker first, then update the tree after every project finding or user answer. Close a branch only when project facts or the user fully answer it. ## Codebase-Answerable Branches -Before asking the user, decide whether project inspection could fully answer the branch. If yes, use focused project exploration for existing patterns, available APIs, file locations, naming conventions, tests, configuration, dependencies, and shipped behaviour. +Before asking the user, decide whether project inspection could fully answer the branch. If yes, inspect focused evidence: patterns, APIs, file locations, naming, tests, config, dependencies, shipped behaviour. -Do not treat existing code as proof of product intent when intent is unclear. If inspection reveals the current state but not the desired outcome, use the finding to make a recommended answer, then ask the user. +Do not treat existing code as product intent when intent is unclear. If inspection reveals current state but not desired outcome, use it to recommend an answer, then ask. ## User Questioning -Relentlessly ask the user one question at a time. Keep each question decision-oriented and easy to answer. There is no limit on the number of questions; keep going until shared understanding is reached. Do not stop because the likely answer seems obvious, because many questions have already been asked, or because project inspection provided adjacent facts. +Relentlessly ask one question at a time. Keep each question decision-oriented and easy to answer. Keep going until shared understanding is reached; do not stop because the answer seems obvious, many questions were asked, or inspection found adjacent facts. ```markdown Question: @@ -41,13 +41,13 @@ Options: - ``` -Do not list more than 3 alternatives beyond the recommendation. Do not ask multi-part questions. If multiple decisions are related, ask the prerequisite decision first and let the next branch depend on that answer. +Do not list more than 3 alternatives beyond the recommendation. Do not ask multi-part questions. If decisions are related, ask the prerequisite first and let the next branch depend on that answer. ## Shared Understanding -Continue walking the decision tree until no blocking branches remain. Shared understanding means the agent can state the intended outcome, constraints, important tradeoffs, acceptance criteria without inventing product or codebase facts. +Walk the decision tree until no blocking branches remain. Shared understanding means the agent can state outcome, constraints, tradeoffs, and acceptance criteria without inventing product or codebase facts. -When unsure whether a branch is blocking, treat it as blocking and ask the user. Do not complete interrogation with silent assumptions, unresolved branches, or TODO-style follow-ups for later workflow stages. +When unsure whether a branch blocks, treat it as blocking and ask. Do not finish with silent assumptions, unresolved branches, or TODO-style follow-ups. ## Handoff Summary diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md index 822757c..caeb500 100644 --- a/skills/plan/SKILL.md +++ b/skills/plan/SKILL.md @@ -5,7 +5,7 @@ description: Create an implementation-ready feature plan from an approved PRD us # Plan -Turn an approved PRD into a phased implementation-ready plan using vertical slices. +Turn an approved PRD into a phased, vertical-slice implementation plan. ## Prerequisites @@ -18,10 +18,10 @@ ALL prerequisites MUST be satisfied BEFORE following this skill. Follow these steps IN ORDER. Do NOT skip steps. -1. Review the approved `prd.md` to get a complete understanding of the feature. +1. Review the approved `prd.md` to understand the feature completely. 2. Explore relevant areas of the codebase for fresh context. -3. Load any non-Propulsion skills relevant to the PRD that are not already active or present in context, and use them to help inform the plan. -4. Write `docs/propulsion/{yyyymmdd}-{feature-name}/plan.md` using the template in [references/plan-template.md](references/plan-template.md). +3. Load relevant non-Propulsion skills not already active or present in context, and use them to inform the plan. +4. Write `docs/propulsion/{yyyymmdd}-{feature-name}/plan.md` from [references/plan-template.md](references/plan-template.md). 5. Start a fresh plan review subagent with the prompt in [references/plan-reviewer-prompt.md](references/plan-reviewer-prompt.md). 6. Review and implement feedback from the plan review. 7. Repeat steps 5 and 6 until the review returns `Status: approved`. @@ -33,7 +33,7 @@ Follow these steps IN ORDER. Do NOT skip steps. These rules are MANDATORY. - NEVER skip reviewing the PRD, exploring the codebase, or loading missing relevant skills. -- ALWAYS use the plan template reference for structure, section order, and completion rules. +- ALWAYS use the plan template for structure, section order, and completion rules. - NEVER print the full plan in the chat, ONLY write it to the file. - MUST use ALL information from the PRD, DO NOT leave any details out even if they seem obvious or minor. - USE `Status: approved` as the ONLY valid review approval signal. diff --git a/skills/plan/references/plan-reviewer-prompt.md b/skills/plan/references/plan-reviewer-prompt.md index eb95b28..104333d 100644 --- a/skills/plan/references/plan-reviewer-prompt.md +++ b/skills/plan/references/plan-reviewer-prompt.md @@ -5,29 +5,29 @@ Use this template when starting a fresh plan review subagent in the `plan` skill ````markdown **You are a subagent completing work in the Propulsion workflow.** -You are a plan document reviewer. Verify that the plan is implementation ready and conforms to the plan template. +Review whether the plan is implementation-ready and conforms to the plan template. **Plan document location**: `docs/propulsion/.../plan.md` **Source PRD location**: `docs/propulsion/.../prd.md` ## Review Criteria -| Category | What to verify | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Source Alignment | The plan preserves all relevant PRD decisions, implementation inputs, testing decisions, constraints, and scope boundaries. | -| Requirements Traceability | Every PRD user story, functional requirement, and non-functional requirement appears in the Requirements Coverage Matrix and is covered by at least one phase and one acceptance criterion. | -| Acceptance Criteria Coverage | Acceptance criteria use exact PRD IDs, cover the mapped requirements, are observable/testable, and are specific enough to verify implementation. | -| Vertical Slice Design | Phases are thin vertical slices delivering narrow end-to-end behaviour, not horizontal layers or vague milestones. | -| Phase Completeness | Each phase includes enough schema, backend, API, UI, validation, authorisation, testing, logging, documentation, or other relevant layer work to deliver its stated behaviour. | -| Skills Coverage | Relevant skills are recommended globally and per phase, no obviously required skill is missing, and no irrelevant skill is recommended. | -| Testing Coverage | Each phase has a testing plan that validates its acceptance criteria and covers the important public behaviours and seams. | -| Scope Control | Required work is included, speculative work is excluded, and no product behaviour is invented beyond the approved PRD. | -| Sequencing & Dependencies | Phase order is workable, dependencies are respected, and the plan will not force avoidable rework or dead ends later. | -| Phase Specificity | Each phase gives the worker enough context to act: clear goal, demo / verification outcome, likely areas, constraints, implementation notes, acceptance criteria, and testing plan. | -| Decision Hygiene | Durable decisions are captured once at the right level, with no contradictions or re-litigation points across phases. | -| Template Conformity | The plan follows the required template structure, section order, tables, and conventions. | - -Flag only issues that would cause implementation to build the wrong thing, miss required scope, get stuck, or need re-planning. +| Category | Verify | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Source Alignment | Preserves PRD decisions, inputs, testing decisions, constraints, and scope boundaries. | +| Requirements Traceability | Every PRD user story, functional requirement, and non-functional requirement appears in the matrix and is covered by at least one phase and criterion. | +| Acceptance Criteria Coverage | Criteria use exact PRD IDs, cover mapped requirements, are observable/testable, and specific enough to verify. | +| Vertical Slice Design | Phases are thin vertical slices delivering narrow end-to-end behaviour, not horizontal layers or vague milestones. | +| Phase Completeness | Each phase includes enough relevant layer work to deliver its stated behaviour. | +| Skills Coverage | Relevant skills are recommended globally/per phase; no obviously required skill is missing; no irrelevant skill is recommended. | +| Testing Coverage | Each phase has a testing plan that validates criteria and important public behaviours/seams. | +| Scope Control | Required work is included, speculative work is excluded, and no product behaviour is invented beyond the PRD. | +| Sequencing & Dependencies | Phase order is workable, dependencies are respected, and avoidable rework/dead ends are not forced. | +| Phase Specificity | Each phase gives enough context: goal, demo outcome, likely areas, constraints, notes, criteria, and testing plan. | +| Decision Hygiene | Durable decisions are captured once at the right level without contradictions or re-litigation points. | +| Template Conformity | Required template structure, section order, tables, and conventions are followed. | + +Flag only issues that would make implementation build the wrong thing, miss required scope, get stuck, or require re-planning. ## Instructions @@ -73,7 +73,7 @@ Use this exact format for your output. These rules are MANDATORY. -- NEVER skip any part of the review criteria +- NEVER skip any review criterion. - ENSURE every part of the PRD is considered in the review, even if it seems obvious or minor. - EVERY PRD user story, functional requirement, and non-functional requirement MUST be traceable to at least one phase and one acceptance criterion in the plan. - MUST return exactly one `Status:` line with either `approved` or `rejected`. diff --git a/skills/plan/references/plan-template.md b/skills/plan/references/plan-template.md index 5e45c33..83b9a88 100644 --- a/skills/plan/references/plan-template.md +++ b/skills/plan/references/plan-template.md @@ -11,14 +11,14 @@ Use the `execute` skill to implement this plan and track progress using the chec ## Durable Decisions -List decisions that apply globally across all phases. +List global phase decisions. - Decision 1 - Decision 2 ## Relevant Skills -List every agentic skill that may be needed while implementing this plan. +List every agentic skill that may be needed during implementation. | Skill | Required For | Details | | -------------- | ---------------- | ------------------------------------------ | @@ -26,9 +26,7 @@ List every agentic skill that may be needed while implementing this plan. ## Requirements Coverage Matrix -Every PRD user story, functional requirement, and non-functional requirement MUST be represented here. - -Use exact IDs from the PRD. Do NOT rename, merge, or invent IDs. +Every PRD user story, functional requirement, and non-functional requirement MUST appear here. Use exact PRD IDs; do NOT rename, merge, or invent IDs. | PRD ID | Type | Covered By Phase(s) | Covered By Acceptance Criteria | Notes | | ------- | -------------------------- | ------------------- | ------------------------------ | ----- | @@ -40,7 +38,7 @@ Use exact IDs from the PRD. Do NOT rename, merge, or invent IDs. **Status**: [ ] Phase complete -**Goal**: Describe the narrow end-to-end behaviour this phase implements. The goal MUST describe a complete user-visible, system-visible, or test-verifiable outcome. +**Goal**: Describe the narrow end-to-end behaviour this phase implements as a complete user-visible, system-visible, or test-verifiable outcome. **Demo / Verification Outcome**: Describe exactly how someone can verify this phase is complete without inspecting implementation details. @@ -52,38 +50,36 @@ Use exact IDs from the PRD. Do NOT rename, merge, or invent IDs. **Likely Areas**: -Use exact file paths only when they are durable and important. Prefer directories or modules when exact files may change. +Use exact paths only when durable and important. Prefer directories or modules when files may change. - `src/...` - `tests/...` **Constraints**: -List the durable constraints this phase MUST respect. +List durable constraints this phase MUST respect. - Constraint 1 - Constraint 2 **Implementation Notes**: -Provide enough implementation context that a subagent can start work without rediscovering scope. Do NOT invent product decisions that are absent from the PRD. +Provide enough context to start without rediscovering scope. Do NOT invent product decisions absent from the PRD. - Note 1 - Note 2 **Acceptance Criteria**: -Each acceptance criterion MUST reference at least one PRD user story, functional requirement, or non-functional requirement unless the criterion is purely functional and no NFR applies. +Each acceptance criterion MUST reference at least one PRD user story, functional requirement, or non-functional requirement unless purely functional with no NFR. -| ID | Acceptance Criterion | User Story ID(s) | Functional Requirement ID(s) | Non-Functional Requirement ID(s) | -| ------ | ------------------------------------------------------------ | ---------------- | ---------------------------- | -------------------------------- | -| AC-001 | Given , when , then . | US-001 | FR-001 | NFR-001 | -| AC-002 | Given , when , then . | US-001 | FR-002 | NFR-002 | -| AC-003 | can . | US-001 | FR-001, FR-002 | NFR-001 | +| ID | Acceptance Criterion | User Story ID(s) | Functional Requirement ID(s) | Non-Functional Requirement ID(s) | +| ------ | ---------------------------------------------------------- | ---------------- | ---------------------------- | -------------------------------- | +| AC-001 | Given , when , then . | US-001 | FR-001 | NFR-001 | **Testing Plan**: -Describe the public behaviours and seams that MUST be tested for this phase. +Describe public behaviours and seams that MUST be tested for this phase. | Test Level | Required Coverage | | --------------------- | ----------------- | diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md index 45efeef..7d66933 100644 --- a/skills/pr/SKILL.md +++ b/skills/pr/SKILL.md @@ -5,7 +5,7 @@ description: Create or reuse a GitHub pull request from the current branch with # Pull Request -Create or reuse one GitHub pull request from the current branch and report the verified result. +Create or reuse one GitHub pull request and report the verified result. ## Prerequisites @@ -19,12 +19,12 @@ ALL prerequisites MUST be satisfied BEFORE following this skill. Follow these steps IN ORDER. Do NOT skip steps. 1. Resolve the base branch from optional user input, or default to the repo's main development branch. -2. Collect context first with the git commands in [references/workflow.md](references/workflow.md). -3. If the current branch equals the base branch, stop and ask the user to confirm the intended base branch. +2. Collect context first with [references/workflow.md](references/workflow.md). +3. If the current branch equals the base branch, stop and ask the user to confirm the intended base. 4. If the worktree is dirty, load and invoke the `commit` skill with no extra instructions, then refresh branch context before PR metadata. 5. Push safely: use `git push -u origin ` when no upstream exists; otherwise use `git push`. 6. Check for an existing open PR for the current head branch. -7. If an open PR exists with a different base, stop and ask whether to update the base; only if confirmed, run `gh pr edit --base ` before title or body refresh. +7. If an open PR exists with a different base, stop and ask whether to update it; only if confirmed, run `gh pr edit --base ` before title or body refresh. 8. If an open PR exists on the chosen base, reuse it unchanged when no commit delta exists; otherwise ask whether to refresh title and body, then use `gh pr edit` only after explicit confirmation. 9. If no open PR exists and no commit delta exists, output exactly `No PR changes to open.` 10. Generate a Conventional Commit PR title and summary body from the complete `...HEAD` history and diff. @@ -39,7 +39,7 @@ These rules are MANDATORY. - MUST use the complete branch history and diff, not only the latest commit, for title and body. - MUST keep the PR title a valid Conventional Commit subject suitable for squash merge history. - NEVER force push, reset, amend older commits, change git config, or bypass hooks. -- ALWAYS stop and report the failing command plus one concrete unblock action for GitHub CLI auth, permission, or remote access failures. +- ALWAYS stop and report the failing command plus one unblock action for GitHub CLI auth, permission, or remote access failures. ## Completion Gate diff --git a/skills/pr/references/workflow.md b/skills/pr/references/workflow.md index 1df9c80..0c8da32 100644 --- a/skills/pr/references/workflow.md +++ b/skills/pr/references/workflow.md @@ -2,8 +2,8 @@ ## Inputs -- Optional base branch input: treat any explicit user-provided branch name as ``. -- If no base is provided, use the repo's main development branch, such as `main` or the branch pointed to by `origin/HEAD`. +- Treat any explicit user-provided branch name as ``. +- If no base is provided, use the repo's main development branch, such as `main` or `origin/HEAD`. ## Context Commands @@ -24,7 +24,7 @@ After invoking the `commit` skill for a dirty worktree, refresh: ## Existing PR Handling -Check for an existing open PR for the current head branch: +Check for an open PR for the current head branch: ```sh gh pr list --head --state open --json url,number,title,body,baseRefName,headRefName @@ -33,21 +33,21 @@ gh pr list --head --state open --json url,number,title,body,baseRefName - If the PR base differs from ``, stop and ask whether to correct the PR base. - If the user explicitly agrees, update the base before any title or body refresh: `gh pr edit --base `. - If the user declines or gives an unclear answer, stop and ask them to rerun the PR skill with the intended base branch. -- If the PR base matches `` and no commit delta exists, reuse the PR unchanged, verify it, and report the success output. +- If the PR base matches `` and no commit delta exists, reuse unchanged, verify, and report success output. - If the PR base matches `` and a commit delta exists, show the URL and ask whether to refresh title and summary. - If the user explicitly agrees, update only title and body with `gh pr edit --title "" --body "<body>"`. -- If the user declines or gives an unclear answer, reuse the PR unchanged, verify it, and report the success output. +- If the user declines or gives an unclear answer, reuse unchanged, verify, and report success output. ## Push Safety - If the branch has no upstream, run `git push -u origin <branch>`. - If the branch has an upstream, run `git push`. - Never force push. -- If push fails because authentication, permissions, or remote access requires user action, stop and report the failing command with one concrete unblock action. +- If push fails due to auth, permissions, or remote access, stop and report the failing command plus one concrete unblock action. ## PR Metadata -Infer the title and summary from the full `<base>...HEAD` commit history, diff, and diff stat. +Infer title and summary from the full `<base>...HEAD` commit history, diff, and diff stat. Allowed Conventional Commit title types: diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md index a47199d..2255386 100644 --- a/skills/review/SKILL.md +++ b/skills/review/SKILL.md @@ -5,7 +5,7 @@ description: Review PRs and ref ranges with senior-level findings, validation, a # Review -Review a PR or ref range like a senior engineer and return a validated report. +Review a PR or ref range and return a validated senior-engineer report. ## Prerequisites @@ -18,7 +18,7 @@ ALL prerequisites MUST be satisfied BEFORE following this skill. Follow these steps IN ORDER. Do NOT skip steps. -1. Resolve review scope and allowed context with [references/mode-selection.md](references/mode-selection.md). Stop and ask for a PR number, PR URL, or `base...head` when scope is unclear. +1. Resolve review scope and allowed context with [references/mode-selection.md](references/mode-selection.md); stop and ask for a PR number, PR URL, or `base...head` when scope is unclear. 2. Dispatch fresh reviewer subagents in parallel with [references/reviewer-prompt.md](references/reviewer-prompt.md). Cover the axes in [references/review-axes.md](references/review-axes.md). 3. Dispatch fresh validator subagents with [references/validator-prompt.md](references/validator-prompt.md). Discard anything unconfirmed. 4. Produce the final report exactly as defined in [references/report-format.md](references/report-format.md). Use only `approve`, `approve-with-comments`, `request-changes`, or `needs-clarification`. diff --git a/skills/review/references/issue-schema.md b/skills/review/references/issue-schema.md index fa5e624..4b8ea45 100644 --- a/skills/review/references/issue-schema.md +++ b/skills/review/references/issue-schema.md @@ -1,6 +1,6 @@ # Issue Schema -Use this reference when normalising candidate findings and questions before validation. +Use when normalising candidate findings and questions before validation. ```json { @@ -28,13 +28,13 @@ Use this reference when normalising candidate findings and questions before vali - `kind`, `severity`, `category`, `summary`, `evidence`, `evidence_type`, `impact`, `confidence`, and `validator_verdict` are mandatory. - `kind` MUST be `finding` or `question`. -- `file` and `line` are required for code-based findings. DO omit them only for pure intent or rule questions. +- `file` and `line` are required for code-based findings; omit them only for pure intent or rule questions. - `severity` MUST be one of `critical`, `high`, `medium`, `low`, `nitpick`, `question`. - `category` MUST be one of `rule-violation`, `skill-contract-violation`, `bug`, `compile-break`, `logic-error`, `security`, `performance`, `architecture`, `maintainability`, `duplication`, `test-gap`, `requirement-drift`, or `consistency-drift`. -- `evidence` MUST be concrete and directly tied to changed code, scoped rule text, or cited precedent. +- `evidence` MUST be concrete and tied to changed code, scoped rule text, or cited precedent. - `evidence_type` MUST be `diff`, `rule-text`, `precedent`, `principle`, or `intent-context`. - `confidence` MUST be integer `0-100`. -- `blocking` is required for findings. Set it to `true` only when shipping the issue would create material production, security, UX, or maintenance risk. +- `blocking` is required for findings; set `true` only for material production, security, UX, or maintenance risk. - `rule_source` is required for `rule-violation` and `skill-contract-violation`. - `precedent_refs` is required for `consistency-drift` and any precedent-backed finding. - `intent_refs` is required for `requirement-drift` and any intent-backed finding. diff --git a/skills/review/references/mode-selection.md b/skills/review/references/mode-selection.md index 84bc41c..b7c5db9 100644 --- a/skills/review/references/mode-selection.md +++ b/skills/review/references/mode-selection.md @@ -1,6 +1,6 @@ # Mode Selection -Use this reference when resolving review scope. +Use when resolving review scope. ## Accepted Forms @@ -16,14 +16,14 @@ No other scope forms are supported. - Accept GitHub PR URLs as explicit PR scope. - Require `gh` installed, authenticated, and able to access the repository only for PR scopes. - Resolve PR scope with `gh pr view <number-or-url> --json number,title,body,baseRefName,headRefName,headRefOid,baseRefOid,files,url`. -- Use GitHub PR metadata for base ref, head ref, changed files, title, body, and linked artefact discovery. -- If PR lookup fails, ask one corrective follow-up for a valid PR number or URL instead of guessing another PR. +- Use PR metadata for base/head refs, changed files, title, body, and linked artefact discovery. +- If lookup fails, ask one corrective follow-up for a valid PR number or URL; do not guess another PR. ## Range Scope - Confirm range input contains exactly one `...` separator with non-empty `base` and `head` refs. - Validate both refs with `git rev-parse --verify <ref>^{commit}` before reviewing. -- If either ref is missing or invalid, ask one corrective follow-up for a valid `base...head` range; do not substitute another ref. +- If either ref is missing/invalid, ask one corrective follow-up for a valid `base...head` range; do not substitute another ref. - Review the merge-base diff for the exact range, equivalent to `git diff <base>...<head>`. - Use changed files from the exact merge-base diff. - Use explicit user-stated review goals when intent context is needed. diff --git a/skills/review/references/report-format.md b/skills/review/references/report-format.md index 07bb2af..62ad012 100644 --- a/skills/review/references/report-format.md +++ b/skills/review/references/report-format.md @@ -1,10 +1,6 @@ # Report Format -Use this reference when producing the final review report. - -Use this exact report shape for both PR and `base...head` reviews. - -If the resolved review scope is empty, still return this exact format. +Use this exact final report shape for PR and `base...head` reviews, including empty scopes. ```markdown # Review Report @@ -31,37 +27,19 @@ If the resolved review scope is empty, still return this exact format. - None -<or> - -- <short title> - - Location: <path:line | scope area> - - Why it matters: <concrete impact> - - Evidence: <quoted diff, rule text, precedent, or intent evidence> - - Recommended action: <smallest safe improvement> +<or same finding item shape as Critical> **Medium Findings** - None -<or> - -- <short title> - - Location: <path:line | scope area> - - Why it matters: <concrete impact> - - Evidence: <quoted diff, rule text, precedent, or intent evidence> - - Recommended action: <smallest safe improvement> +<or same finding item shape as Critical> **Low Findings** - None -<or> - -- <short title> - - Location: <path:line | scope area> - - Why it matters: <concrete impact> - - Evidence: <quoted diff, rule text, precedent, or intent evidence> - - Recommended action: <smallest safe improvement> +<or same finding item shape as Critical> **Nitpicks** diff --git a/skills/review/references/review-axes.md b/skills/review/references/review-axes.md index 3128ed3..af3136f 100644 --- a/skills/review/references/review-axes.md +++ b/skills/review/references/review-axes.md @@ -1,27 +1,21 @@ # Review Axes -Use this reference when dispatching the focused reviewer passes. +Use when dispatching focused reviewer passes. ## Focused reviewer passes -- Correctness - - Verify changed behaviour against the stated intent, edge cases, failure paths, state transitions, data flow, and dependency changes. -- Security / trust boundaries - - Inspect auth, authorization, validation, injection surfaces, secrets, config, logging, file handling, and integration boundaries. -- Maintainability / architecture - - Look for wrong-layer ownership, second sources of truth, duplicated business logic, concrete refactoring opportunities, abstraction leakage, coupling, unnecessary complexity, and unnecessary indirection. - - Apply `DRY`, `single-source-of-truth`, `separation-of-concerns`, `ownership-boundary`, `cohesion`, `encapsulation`, `complexity-management`, `abstraction-leakage`, `SOLID`, and `YAGNI` only when the impact is concrete in the changed code. -- Tests / verification - - Check whether changed behaviour is actually protected by tests or other verification, including realistic failure modes and regressions. -- Intent / rule alignment - - Compare the diff against PR intent, explicitly linked planning artefacts, scoped `AGENTS.md` / `CLAUDE.md`, touched command or skill contracts, and dominant local precedent when consistency matters. +- Correctness: changed behaviour vs stated intent, edge cases, failure paths, state transitions, data flow, and dependency changes. +- Security / trust boundaries: auth, authorization, validation, injection surfaces, secrets, config, logging, file handling, and integration boundaries. +- Maintainability / architecture: wrong-layer ownership, second sources of truth, duplicated business logic, concrete refactoring opportunities, abstraction leakage, coupling, unnecessary complexity, and unnecessary indirection. Apply named principles only when impact is concrete in changed code. +- Tests / verification: changed behaviour protected by tests or other verification, including realistic failure modes and regressions. +- Intent / rule alignment: diff vs PR intent, linked planning artefacts, scoped `AGENTS.md` / `CLAUDE.md`, touched command/skill contracts, and dominant local precedent when consistency matters. ## Alignment rules - Review like a senior PR reviewer, not a lint pass. -- Improve overall code health; do not seek perfection. +- Improve code health; do not seek perfection. - Prefer concrete, merge-relevant issues the author would fix. -- Read code in context, not only the diff hunk. +- Read code in context, not only diff hunks. - Treat tests and trust-boundary changes as first-class review scope. - Use exact evidence, quoted rules, and nearby precedent before broad principles. diff --git a/skills/review/references/reviewer-prompt.md b/skills/review/references/reviewer-prompt.md index 23cc3ee..23b4f76 100644 --- a/skills/review/references/reviewer-prompt.md +++ b/skills/review/references/reviewer-prompt.md @@ -3,7 +3,7 @@ Use this reference when dispatching a fresh reviewer subagent for one review axis. ````markdown -You are a senior code reviewer responsible for exactly one review axis in a PR-style code review. +You review exactly one axis in a PR-style code review. ## Inputs @@ -15,21 +15,21 @@ You are a senior code reviewer responsible for exactly one review axis in a PR-s ## Review Focus -| Axis | What to look for | Do not report | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| Correctness | Broken logic, wrong branches, unsafe state transitions, dependency regressions, deterministic runtime failures | Style nits, hypothetical failures with no evidence | -| Security / trust boundaries | Auth/authz mistakes, missing validation, injection surfaces, secrets/config leaks, unsafe integrations | Generic security advice not triggered by the diff | -| Maintainability / architecture | Wrong ownership, second sources of truth, duplicated business logic, concrete refactoring opportunities, abstraction leakage, harmful complexity, and unnecessary indirection | Broad refactor wishes, future-proofing speculation | -| Tests / verification | Missing protection for changed behaviour, realistic regressions, weak failure-path coverage | Complaints not tied to changed behaviour | -| Intent / rule alignment | Drift from stated PR intent, linked artefacts, scoped rules, or dominant precedent | Hidden requirements or unstated preferences | +| Axis | Look for | Do not report | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | +| Correctness | Broken logic, wrong branches, unsafe state transitions, dependency regressions, deterministic runtime failures | Style nits, unevidenced hypothetical failures | +| Security / trust boundaries | Auth/authz mistakes, missing validation, injection surfaces, secrets/config leaks, unsafe integrations | Generic security advice not triggered by the diff | +| Maintainability / architecture | Wrong ownership, second sources of truth, duplicated business logic, concrete refactoring opportunities, abstraction leakage, harmful complexity, unnecessary indirection | Broad refactor wishes, future-proofing speculation | +| Tests / verification | Missing protection for changed behaviour, realistic regressions, weak failure-path coverage | Complaints not tied to changed behaviour | +| Intent / rule alignment | Drift from PR intent, linked artefacts, scoped rules, or dominant precedent | Hidden requirements or unstated preferences | ## Instructions Follow these steps IN ORDER. Do NOT skip steps. 1. Review only the assigned axis. -2. Inspect the changed files and only the allowed context. -3. Compare the diff against the assigned axis and identify only merge-relevant candidates. +2. Inspect changed files and only allowed context. +3. Compare the diff against the assigned axis; keep only merge-relevant candidates. 4. Normalise every candidate using `references/issue-schema.md`. 5. Return candidates only. Do not write final review prose. @@ -48,6 +48,8 @@ Return `[]` when no candidates survive the reviewer pass. ## Rules +These rules are MANDATORY. + - ALWAYS stay inside the assigned axis. - ALWAYS stay inside the allowed review scope and allowed context. - DO return only normalised candidates. diff --git a/skills/review/references/validation-rubric.md b/skills/review/references/validation-rubric.md index bc47763..51c321c 100644 --- a/skills/review/references/validation-rubric.md +++ b/skills/review/references/validation-rubric.md @@ -1,19 +1,18 @@ # Validation Rubric -Use this reference when validating candidate findings and questions before final report generation. +Use when validating candidate findings and questions before final report generation. ## Disprove-first flow 1. Assume the finding is wrong. -2. Search the diff, full changed files, scoped rules/contracts, and gathered adjacent context for counter-evidence. +2. Search diff, changed files, scoped rules/contracts, and gathered adjacent context for counter-evidence. 3. Reject if evidence is incomplete, ambiguous, pre-existing, or out of scope. 4. Confirm only if objective evidence supports the claim and the issue is one the PR author would fix. ## Candidate types - Validate `finding` candidates and `question` candidates separately. -- A `question` is valid only when missing context materially blocks the final decision or severity. -- A `question` must cite the exact missing artefact, assumption, or unresolved behaviour. +- A `question` is valid only when missing context materially blocks final decision or severity and cites the exact missing artefact, assumption, or unresolved behaviour. ## Severity confirmation requirements @@ -38,11 +37,10 @@ Use this reference when validating candidate findings and questions before final ## Evidence requirements -- Evidence must come from changed code, scoped rules/contracts, allowed adjacent context, nearby precedent, or explicitly linked intent artefacts. -- Rule or contract violations must quote exact text and source path. -- Consistency claims must cite dominant local precedent. -- Principle-backed claims must name the principle and explain the concrete maintenance, ownership, testing, or correctness cost. -- Test-gap claims must tie directly to changed behaviour and realistic failure modes. +- Evidence must come from changed code, scoped rules/contracts, allowed adjacent context, nearby precedent, or linked intent artefacts. +- Rule/contract violations quote exact text and source path; consistency claims cite dominant local precedent. +- Principle-backed claims name the principle and concrete maintenance, ownership, testing, or correctness cost. +- Test-gap claims tie directly to changed behaviour and realistic failure modes. ## Automatic reject conditions diff --git a/skills/review/references/validator-prompt.md b/skills/review/references/validator-prompt.md index 1e6c671..50b751d 100644 --- a/skills/review/references/validator-prompt.md +++ b/skills/review/references/validator-prompt.md @@ -1,9 +1,9 @@ # Validator Prompt Template -Use this reference when dispatching a fresh validator subagent for one normalised candidate. +Use when dispatching a fresh validator subagent for one normalised candidate. ````markdown -You are a validator for one candidate finding or question from a senior PR review workflow. +You validate one candidate finding or question from a senior PR review workflow. ## Inputs diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index 0f3e881..d3d665a 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -21,19 +21,19 @@ ALL prerequisites MUST be satisfied BEFORE following this skill. Follow these steps IN ORDER. Do NOT skip steps. 1. Choose the smallest thin vertical slice that delivers one observable behaviour end-to-end; state the interface, expected outcome, and narrowest test command. -2. Apply the gate in [references/testing-patterns.md](references/testing-patterns.md). If no valuable behavioural test exists, record the no-test rationale and strongest fallback verification before changing code. +2. Apply [references/testing-patterns.md](references/testing-patterns.md). If no valuable behavioural test exists, record the no-test rationale and strongest fallback verification before changing code. 3. Write ONE failing test through a public interface or stable seam for the next behaviour only. 4. Run the narrowest test command and confirm the test fails for the expected reason. -5. Write the minimum production code to pass; keep fixtures small and mock only real external, slow, unstable, or nondeterministic boundaries. +5. Write minimum passing production code; keep fixtures small and mock only real external, slow, unstable, or nondeterministic boundaries. 6. Re-run the narrowest test command and confirm green. -7. Review refactor candidates only after green using [references/refactor-candidates.md](references/refactor-candidates.md); refactor in small behaviour-preserving steps and rerun relevant checks. +7. Review refactor candidates only after green using [references/refactor-candidates.md](references/refactor-candidates.md); refactor in small behaviour-preserving steps and rerun checks. 8. Repeat slice by slice until the requested behaviour is complete. ## Rules These rules are MANDATORY. -- NEVER write production code before a failing test WHEN a valuable behavioural test exists. +- NEVER write production code before a failing test when a valuable behavioural test exists. - ALWAYS test observable behaviour through a public interface or stable seam. - NEVER add source-text checks, private-structure checks, internal call choreography, broad snapshots, speculative tests, or implementation-detail tests as behavioural proof. - DO NOT over-mock; ONLY mock real boundaries that are external, slow, unstable, nondeterministic, or too expensive for the selected test scope. diff --git a/skills/tdd/references/refactor-candidates.md b/skills/tdd/references/refactor-candidates.md index 0ff8dad..7012a35 100644 --- a/skills/tdd/references/refactor-candidates.md +++ b/skills/tdd/references/refactor-candidates.md @@ -1,12 +1,10 @@ # Refactor Candidates -Use this guide only after red-green is green. Refactor to remove present design pressure while preserving behaviour. +Use only after red-green is green. Refactor to remove present design pressure while preserving behaviour. ## When To Refactor -Refactor when all relevant checks are green and you can name a real improvement. - -Good reasons: +Refactor when checks are green and you can name a real improvement. Good reasons: - the next change is harder than it should be; - a rule is duplicated and starting to drift; @@ -15,7 +13,7 @@ Good reasons: - branches or data shapes obscure the domain rule; - a small move would reduce current risk or confusion. -Do one structural idea at a time. Stop when the current pain is removed. +Do one structural idea at a time; stop when current pain is removed. ## When Not To Refactor @@ -34,59 +32,31 @@ Use YAGNI: reject abstractions for futures the code does not need today. ### Duplicated Knowledge -Look for the same decision, validation, calculation, workflow, or domain phrase in multiple places. - -Why it matters: copies drift and fixes land in only one place. - -Improve it by extracting the shared rule, moving it to the owner, or introducing a small abstraction only after real call sites need it. +Look for the same decision, validation, calculation, workflow, or domain phrase in multiple places. Copies drift and fixes land in one place. Improve by extracting the shared rule, moving it to the owner, or introducing a small abstraction only after real call sites need it. ### Mixed Responsibilities -Look for one function or module that validates, calculates, persists, formats, and coordinates at once. - -Why it matters: unrelated changes collide and tests need excessive setup. - -Improve it by separating orchestration from decisions, moving behaviour to the module with the strongest reason to change, and keeping coordinators thin. +Look for one function/module that validates, calculates, persists, formats, and coordinates. Unrelated changes collide and tests need excessive setup. Improve by separating orchestration from decisions, moving behaviour to the strongest owner, and keeping coordinators thin. ### Poor Names -Look for placeholders, abbreviations, stale names, or test names that describe mechanics instead of behaviour. - -Why it matters: unclear names hide intent and make future changes slower. - -Improve it by renaming variables, functions, types, files, and tests to match domain meaning. +Look for placeholders, abbreviations, stale names, or tests named for mechanics instead of behaviour. Unclear names hide intent and slow changes. Rename variables, functions, types, files, and tests to match domain meaning. ### Long Or Tangled Flow -Look for deep nesting, repeated conditions, order-sensitive branches, or methods that require scrolling and memory. - -Why it matters: bugs hide in paths readers cannot follow. - -Improve it with guard clauses, extracted predicates, named steps, or split cases. Use polymorphism only after duplication makes the cases real. +Look for deep nesting, repeated conditions, order-sensitive branches, or methods that require scrolling. Bugs hide in unreadable paths. Improve with guard clauses, predicates, named steps, or split cases; use polymorphism only after duplication makes cases real. ### Feature Envy -Look for logic that repeatedly pulls fields from another object to make decisions for it. - -Why it matters: behaviour lives away from the data it depends on. - -Improve it by moving the behaviour closer to the data or replacing field chains with messages to the owner. +Look for logic repeatedly pulling fields from another object to decide for it. Move behaviour closer to the data or replace field chains with messages to the owner. ### Primitive Obsession -Look for strings, booleans, numbers, or loose parameter groups that repeatedly encode a domain concept. - -Why it matters: validation and meaning scatter across the codebase. - -Improve it with a small value object, enum, named type, or parameter object when the concept already has behaviour or repeated validation. +Look for strings, booleans, numbers, or loose parameter groups repeatedly encoding a domain concept. Use a small value object, enum, named type, or parameter object when the concept has behaviour or repeated validation. ### Test Friction -Look for tests that need heavy setup, many mocks, private seams, or fragile assertions to prove simple behaviour. - -Why it matters: test pain often exposes design pain. - -Improve production design first when it has real value; do not add test-only seams. +Look for tests needing heavy setup, many mocks, private seams, or fragile assertions for simple behaviour. Test pain often exposes design pain; improve production design when valuable, not test-only seams. ## Safe Moves @@ -102,7 +72,7 @@ Prefer small behaviour-preserving moves: - simplify conditionals; - replace partial mocks with realistic fakes when it improves design pressure. -Run the narrowest relevant check after each meaningful move. If a check fails, fix or revert the last refactor step before continuing. +Run the narrowest relevant check after each meaningful move. If it fails, fix or revert the last refactor step before continuing. ## Filters diff --git a/skills/tdd/references/testing-patterns.md b/skills/tdd/references/testing-patterns.md index dc1e61c..dfbe5eb 100644 --- a/skills/tdd/references/testing-patterns.md +++ b/skills/tdd/references/testing-patterns.md @@ -1,49 +1,32 @@ # Testing Patterns -Use this reference before writing or keeping a TDD test. Keep tests behavioural, refactor-safe, and cheap enough to run during red-green. +Use before writing or keeping a TDD test. Keep tests behavioural, refactor-safe, and cheap enough for red-green. ## When TDD Applies -Use TDD when the task changes observable behaviour, a public contract, or durable business logic. - -Do not force TDD for prose-only docs, comments, prompts, formatting, config text, dependency bumps, generated files, or pure refactors with no behaviour change. Record the no-test rationale and run fallback verification instead. - -If a task mixes behaviour with maintenance, TDD only the behaviour-changing slice. +Use TDD for observable behaviour, public contracts, or durable business logic. Do not force it for prose-only docs, comments, prompts, formatting, config text, dependency bumps, generated files, or pure refactors; record no-test rationale and run fallback verification. If work mixes behaviour and maintenance, TDD only the behaviour-changing slice. ## Test Type Choice -Choose the highest-level test that proves the behaviour while staying quick, deterministic, and cheap. +Choose the highest-level quick, deterministic test that proves behaviour. 1. Prefer feature or integration tests first. Test the public path a caller, user, endpoint, CLI, message handler, or upstream module uses. 2. Use unit tests second for isolated important logic, especially rules with many cases, edge conditions, or awkward setup through the full path. 3. Use browser or end-to-end tests sparingly for UI interaction patterns, smoke coverage, or behaviour that lower-level tests cannot prove. -Drop lower only when the higher-level path is slow, flaky, too broad, or expensive to control. Drop to a stable seam with domain meaning, not a private helper. +Drop lower only when the higher-level path is slow, flaky, too broad, or expensive to control; use a stable domain seam, not a private helper. ## Red-Green Test Quality Write one failing test for one missing behaviour. -Good red tests: - -- name the behaviour in caller language; -- fail for the expected reason before production changes; -- tell you the next smallest code change; -- assert an observable outcome; -- avoid future requirements. +Good red tests name caller-visible behaviour, fail for the expected reason before production changes, imply the next smallest code change, assert observable outcomes, and avoid future requirements. -Weak red tests: - -- assert helper calls, call order, source text, hook names, class names, or private state; -- require large mock choreography; -- fail when internals move but behaviour stays the same; -- cover hypothetical edge cases not requested now. +Weak red tests assert helper calls, call order, source text, hook names, class names, or private state; require large mock choreography; fail when internals move but behaviour stays; or cover hypothetical edge cases. ## Refactor-Safe Tests -Refactor-safe tests keep passing when internals are rewritten but behaviour stays the same. - -Assert through public interfaces or stable seams: +Refactor-safe tests keep passing when internals change but behaviour does not. Assert through public interfaces or stable seams: - returned values; - persisted state through supported reads; @@ -79,37 +62,19 @@ test('calls validateCart before createOrder', async () => { ## Good Tests -Good tests prove a behaviour someone depends on. +Good tests prove a depended-on behaviour through exported functions, endpoints, commands, UI interactions, handlers, or stable domain seams. Keep setup small and realistic; use multiple assertions only for one outcome from one cause; prefer cheap builders, fixtures, in-memory adapters, and real collaborators; make failures describe broken behaviour. -- Test through exported functions, endpoints, commands, UI interactions, handlers, or stable domain seams. -- Keep setup small and realistic. -- Use multiple assertions only when they describe one outcome from one cause. -- Prefer builders, fixtures, in-memory adapters, and real collaborators when they stay cheap. -- Make failures describe broken behaviour, not changed structure. - -Examples: - -- `login(email, password)` rejects invalid credentials. -- `publishPost()` makes the post visible in `listPublishedPosts()`. -- Clicking `Save` shows a success message. +Examples: `login(email, password)` rejects invalid credentials; `publishPost()` makes the post visible in `listPublishedPosts()`; clicking `Save` shows a success message. ## Bad Tests -Reject tests that prove structure instead of behaviour. - -- `checkout()` calls `paymentService.charge()` once. -- `login()` calls `validatePasswordHash()`. -- A component contains `aria-label` as source text. -- A broad snapshot proves a button opens a menu. -- A test exists only because an edge case might matter later. +Reject structure tests: `checkout()` calls `paymentService.charge()` once; `login()` calls `validatePasswordHash()`; source text contains `aria-label`; a broad snapshot proves a menu opens; a test exists only because an edge case might matter later. Replace bad tests with behavioural assertions. If none exists, do not keep a weak test; document the no-test rationale and run fallback verification. ## Mocks And Doubles -Mock only real boundaries that are external, slow, unstable, nondeterministic, or too expensive for the selected scope. - -Good mock targets: +Mock only real boundaries that are external, slow, unstable, nondeterministic, or too expensive for the selected scope. Good targets: - payment gateways; - clocks and time; @@ -118,9 +83,7 @@ Good mock targets: - file systems; - third-party APIs. -Keep core logic real. Prefer fakes that preserve behaviour, such as an in-memory repository or mailer that records sent messages. - -Avoid over-mocking. If mock setup dominates the test, the test likely proves mocks agree with each other. If mock data is required, mirror the real schema enough that consumers cannot accidentally rely on missing fields. +Keep core logic real. Prefer behaviour-preserving fakes, such as an in-memory repository or mailer. If mock setup dominates, the test likely proves mocks agree. If mock data is required, mirror enough real schema to avoid accidental reliance on missing fields. ## Anti-Patterns diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 624a344..a264ee4 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -5,17 +5,17 @@ description: Create or improve reusable skills with compact progressive-disclosu # Write Skill -Create concise skills that package repeatable workflows without bloating context. +Create concise skills for repeatable workflows without bloating context. ## Instructions Follow these steps IN ORDER. Do NOT skip steps. -1. Load `interrogate` skill to gather the skill's job, concrete use cases, expected inputs, expected outputs, and trigger phrases before drafting. +1. Load `interrogate` to gather the skill's job, use cases, expected inputs, expected outputs, and trigger phrases before drafting. 2. Choose the default output path `.agents/skills/{skill-name}/`; keep `name` equal to the directory name. -3. Draft or update `SKILL.md` with the required shape in [assets/skill-template.md](assets/skill-template.md). +3. Draft or update `SKILL.md` using [assets/skill-template.md](assets/skill-template.md). 4. Put only essential workflow in `SKILL.md`; move supporting artefacts into appropriate directories. -5. Put reusable templates or static resources in `assets/`, executable helpers in `scripts/`, and detailed docs in `references/`. +5. Put templates/static resources in `assets/`, executable helpers in `scripts/`, and detailed docs in `references/`. 6. Validate the result with [scripts/validate-skill.js](scripts/validate-skill.js), then fix every blocking issue. ## Rules @@ -28,7 +28,7 @@ These rules are MANDATORY. - MUST keep `SKILL.md` compact: target about 50 body lines and never exceed 80 body lines. - MUST make `description` one line, triggerable, and clear about when the skill should be used. - MUST place artefacts directly under `assets/`, `references/`, or `scripts/` and link each from final references as `- [path](path) - text`. -- MUST use progressive disclosure: metadata first, essential instructions second, artefacts only when needed. +- MUST use progressive disclosure: metadata first, essential instructions second, artefacts as needed. - MUST write short, direct, instructional prose: remove filler, pleasantries, hedging, and verbose phrases while preserving exact technical meaning. - MUST review [references/checklist.md](references/checklist.md) and run [scripts/validate-skill.js](scripts/validate-skill.js) before handoff. diff --git a/skills/write-skill/assets/skill-template.md b/skills/write-skill/assets/skill-template.md index 6d290e2..5d765c4 100644 --- a/skills/write-skill/assets/skill-template.md +++ b/skills/write-skill/assets/skill-template.md @@ -1,6 +1,6 @@ # Skill Authoring Template -Use this template for skills written to `.agents/skills/{skill-name}/SKILL.md` unless the user asks for another supported location. +Use for skills written to `.agents/skills/{skill-name}/SKILL.md` unless the user asks for another supported location. ```markdown --- @@ -55,21 +55,21 @@ Use these references when you need detail. - `name`: use lowercase alphanumeric words joined by single hyphens; match the parent directory exactly. - `name`: keep to 64 characters or fewer. -- `description`: keep one YAML line, action-oriented, third person, and triggerable with `Use when`, `Use for`, or `Use to`. -- `description`: put the main use case and strongest trigger words early because crowded skill lists can shorten descriptions. +- `description`: keep one YAML line, action-oriented, third person, triggerable with `Use when`, `Use for`, or `Use to`. +- `description`: front-load the main use case and trigger words because crowded skill lists can shorten descriptions. - `description`: validator warns over 200 characters and errors over 300 characters. - Title: use a short human-readable H1 that matches the workflow, not necessarily the exact `name`. - One-line purpose: state the repeatable job and outcome in plain language. -- H2 sections must use this canonical order and no other H2 names: `## Prerequisites`, `## Instructions`, `## Rules`, `## Completion Gate`, `## Next Steps`, `## References`. +- H2 sections must use this canonical order and no other names: `## Prerequisites`, `## Instructions`, `## Rules`, `## Completion Gate`, `## Next Steps`, `## References`. - `## Instructions` and `## References` are required. - Each included H2 must start with its template intro sentence; extra text may follow on the same line. -- `## Instructions`: name expected inputs, outputs, and artefacts when they matter to the workflow. +- `## Instructions`: name expected inputs, outputs, and artefacts when relevant. - `## Prerequisites`: optional; include only when conditions can block, redirect, or define valid use. -- `## Rules`: optional; include when durable constraints must override improvisation; write rules with strong UPPERCASE control words like `MUST`, `DO NOT`, `NEVER`, `ONLY`, `STOP`, or `ALWAYS`. +- `## Rules`: optional; include when durable constraints must override improvisation; use strong UPPERCASE control words like `MUST`, `DO NOT`, `NEVER`, `ONLY`, `STOP`, or `ALWAYS`. - `## Completion Gate`: optional; include when the agent must verify explicit end-state checks before leaving. - `## Next Steps`: optional; include only when a workflow handoff, routing choice, or post-completion action exists. - `## References` must be the final H2. -- Reference bullets for artefacts must be exactly `- [path](path) - text`; link text must match href and the short description after the separator is required. +- Reference bullets for artefacts must be exactly `- [path](path) - text`; link text must match href and include the short description. - Only links in the final `## References` section count for artefact coverage. ## Prose Style @@ -77,16 +77,16 @@ Use these references when you need detail. - Write commands, not essays: use direct verbs like Load, Check, Run, Fix, Stop, or Return. - Delete filler, pleasantries, hedging, and setup phrases such as just, really, basically, actually, simply, please, likely, may want to, and happy to. - Prefer short concrete words over verbose phrasing: use fix instead of implement a solution for, use check instead of perform validation of. -- Keep exact technical meaning: preserve required keywords, file paths, commands, API names, error text, safety warnings, and ordering constraints. +- Preserve exact technical meaning: required keywords, paths, commands, API names, error text, safety warnings, and ordering constraints. - Use fragments when clear, but expand any sentence where compression could hide a condition, risk, or handoff. ## Artefact Placement -- `assets/`: templates, starter files, static examples, images, prompts, and other resources copied or adapted into outputs. -- `references/`: checklists, rubrics, explanations, examples, and long context that should not live in `SKILL.md`. -- `scripts/`: executable validation, generation, migration, or inspection helpers the agent can run. -- Prefer instructions over scripts unless deterministic behavior or external tooling is needed; scripts must be self-contained, dependency-light, and report actionable errors. -- Place artefact files directly under `assets/`, `references/`, or `scripts/`; nested directories or nested files are not allowed. +- `assets/`: templates, starter files, static examples, images, prompts, resources copied/adapted into outputs. +- `references/`: checklists, rubrics, explanations, examples, and long context outside `SKILL.md`. +- `scripts/`: executable validation, generation, migration, or inspection helpers. +- Prefer instructions over scripts unless deterministic behavior or external tooling is needed; scripts must be self-contained, dependency-light, and actionable. +- Place artefacts directly under `assets/`, `references/`, or `scripts/`; nested artefact paths are not allowed. Keep `SKILL.md` around 50 body lines and under 80 body lines. Move detail here or into `references/` instead of expanding the main skill. diff --git a/skills/write-skill/references/checklist.md b/skills/write-skill/references/checklist.md index 85968ab..f920e5d 100644 --- a/skills/write-skill/references/checklist.md +++ b/skills/write-skill/references/checklist.md @@ -13,7 +13,7 @@ Use this checklist before handing off a new or updated skill. - [ ] `description` is 300 characters or fewer to avoid validator errors. - [ ] `description` includes what the skill does. - [ ] `description` includes `Use when`, `Use for`, or `Use to`. -- [ ] `description` front-loads the main use case and strongest trigger words because crowded skill lists can shorten descriptions. +- [ ] `description` front-loads the main use case and trigger words because crowded skill lists can shorten descriptions. - [ ] `description` includes natural trigger keywords a user would say. - [ ] `description` is third person and action-oriented. - [ ] `description` starts with a strong action verb such as Create, Validate, Review, Manage, or Execute. @@ -21,13 +21,13 @@ Use this checklist before handing off a new or updated skill. ## Artefact Layout - [ ] Repository skill path defaults to `.agents/skills/{skill-name}/SKILL.md`. -- [ ] `SKILL.md` exists and contains required `name` and `description` frontmatter. +- [ ] `SKILL.md` has required `name` and `description` frontmatter. - [ ] `assets/` contains only reusable templates or static resources. - [ ] `references/` contains detailed documentation, examples, rubrics, or checklists. - [ ] `scripts/` contains only executable helpers and documents how to run them. - [ ] Scripts are used only when deterministic behavior or external tooling is needed. - [ ] Scripts are self-contained, dependency-light, and report actionable errors. -- [ ] Artefact files are directly under `assets/`, `references/`, or `scripts/`; no nested artefact directories or files exist. +- [ ] Artefacts are directly under `assets/`, `references/`, or `scripts/`; no nested artefact paths exist. - [ ] No unnecessary README, changelog, or duplicate auxiliary files were added. ## SKILL.md Body @@ -50,11 +50,11 @@ Use this checklist before handing off a new or updated skill. ## Language Quality -- [ ] Removes filler words such as just, really, basically, actually, and simply. -- [ ] Removes pleasantries and chatty setup such as sure, certainly, happy to, and please. -- [ ] Removes hedging when the instruction is required, including likely, maybe, should probably, and may want to. -- [ ] Replaces verbose phrasing with short direct wording without changing the instruction. -- [ ] Preserves explicit technical meaning: commands, paths, APIs, error text, safety warnings, conditions, and ordering constraints stay exact. +- [ ] Removes filler: just, really, basically, actually, simply. +- [ ] Removes pleasantries/chatty setup: sure, certainly, happy to, please. +- [ ] Removes hedging from required instructions: likely, maybe, should probably, may want to. +- [ ] Replaces verbose phrasing with short direct wording without changing meaning. +- [ ] Preserves exact commands, paths, APIs, error text, safety warnings, conditions, and ordering constraints. ## Progressive Disclosure From 844f66d6dee0a640383295aaf7daa1b89f52f5c0 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Sun, 10 May 2026 20:36:16 +0100 Subject: [PATCH 4/5] Align debug reviewer prompt --- .../debug/references/bug-reviewer-prompt.md | 84 ++++++++++++++----- 1 file changed, 62 insertions(+), 22 deletions(-) diff --git a/skills/debug/references/bug-reviewer-prompt.md b/skills/debug/references/bug-reviewer-prompt.md index 7efdfea..ef3ddf1 100644 --- a/skills/debug/references/bug-reviewer-prompt.md +++ b/skills/debug/references/bug-reviewer-prompt.md @@ -7,6 +7,8 @@ Use this template when starting a fresh bug-reviewer subagent for one bug-fix lo You are a sceptical implementation reviewer for one bug-fix attempt under the `debug` skill. +Review the bug-fix attempt like a senior engineer: verify the actual implementation against `debug.md`, the original bug behaviour, diagnosis evidence, tests, maintainability, security, reliability, and regression risk. + ## Inputs - **Debug artifact**: `<docs/propulsion/.../debug.md>` @@ -17,27 +19,38 @@ This is the bug-worker report. **Treat it as context, not proof; verify every cl <Copy and paste the full implementation report, excluding the title, from the bug-worker here> -## Review Focus +## Review Criteria + +| Category | Verify | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Diagnosis Integrity | `debug.md` has the required diagnosis evidence before production-code changes, and the evidence still explains the original bug without contradictions. | +| Original Bug Correctness | The implementation fixes the reported bug behaviour itself, not only adjacent symptoms or the worker's preferred repro path. | +| Hypothesis / Constraints Fit | The change stays within the chosen hypothesis, fix constraints, affected boundaries, and prior reset evidence in `debug.md`; speculative or symptom-masking changes are rejected. | +| Tests / Verification | Regression-test-first proof is present: failing result for the expected bug before the fix and passing result after, or `tdd` accepted no valuable test with sufficient fallback proof. | +| Maintainability / Refactoring | The fix is clear, cohesive, minimal, and avoids unnecessary complexity, duplicated logic, or hidden changes outside the bug scope. | +| Security / Trust Boundaries | Inputs, permissions, secrets, file access, external calls, prompt boundaries, and other trust boundaries remain safe. | +| Performance / Reliability | The fix avoids avoidable latency, resource waste, flaky behaviour, races, brittle state, or reliability regressions. | +| Integration / Regression Risk | Surrounding APIs, workflows, tests, prompts, feedback loops, and affected boundaries remain compatible. | +| Output Usefulness | Rejections are actionable, evidence-backed, and clear enough for the debug controller or next bug-worker to continue without reinterpretation. | + +Required diagnosis evidence includes exact symptom, reduced repro or flaky classification, full error reading and conclusion, recent-change conclusion, working example or explicit N/A, boundary tracing, first bad boundary and divergence, fix constraints, chosen hypothesis, fail-then-pass proof, and prior-loop reset evidence when applicable. -- Diagnosis gate was satisfied before production-code changes and still explains the bug. -- Reject missing required evidence: exact symptom, reduced repro/flaky classification, full error reading/conclusion, recent-change conclusion, working example or explicit N/A, boundary tracing, first bad boundary/divergence, fix constraints, chosen hypothesis, fail-then-pass proof, or prior-loop reset evidence. -- Regression-test-first requirement was followed. -- Fix matches the chosen hypothesis and constraints in `debug.md`. -- Verification proves the reported bug behaviour, not only adjacent symptoms. -- If the implementation weakens diagnosis or fails verification, require reset to diagnosis. +Flag only real issues supported by `debug.md`, worker report, code, tests, diff, checks, prompts, or workflow rules. ## Instructions Follow these steps IN ORDER. Do NOT skip steps. 1. Read the current `debug.md` and implementation report in full. -2. Inspect the real code, tests, and diff yourself; do not trust the worker report. +2. Inspect the real code, tests, current diff, and check output yourself; do not trust the worker report. 3. Verify the diagnosis gate was complete before the fix and that current evidence has not contradicted it. 4. Verify the test failed first for the expected bug reason, then passed; `debug.md` must show both. If no test, verify `tdd` declared no valuable test and fallback proof is sufficient. 5. Verify the change stays within the chosen hypothesis/constraints, with no symptom masking or unexplained evidence hidden by the patch. 6. Verify checks cover the reported behaviour and affected boundaries. -7. Approve only if gate, hypothesis fit, regression-first proof or accepted no-test rationale, diagnosis status, and verification all hold. -8. If anything fails, reject the attempt and state whether `debug` must reset back to diagnosis. +7. Use the criteria table to evaluate every criterion with evidence. +8. Approve only if gate, hypothesis fit, regression-first proof or accepted no-test rationale, diagnosis status, verification, and every criterion all hold. +9. If anything fails or is unclear, reject the attempt and state whether `debug` must reset back to diagnosis. +10. Return the implementation review report in the exact format below. ## Output @@ -48,30 +61,36 @@ Use this exact format for your output. **Status**: <approved | rejected> +**Criteria Results** + +- <criterion category>: <met | not met | unclear> + - Evidence: <brief proof from `debug.md`, worker report, code, tests, diff, checks, behaviour, prompts, workflow rules, or missing verification> + **Diagnosis Status** - <still holds | contradicted | unclear> - - Evidence: <brief proof from `debug.md`, diff, checks, behaviour, or missing verification> + - Evidence: <brief proof from `debug.md`, worker report, code, tests, diff, checks, behaviour, prompts, workflow rules, or missing verification> **Verification Status** - Regression-test-first requirement: <met | not met | unclear> - - Evidence: <brief proof from code, diff, checks, behaviour, or missing verification> + - Evidence: <brief proof from `debug.md`, worker report, code, tests, diff, checks, behaviour, prompts, workflow rules, or missing verification> - Failing result before fix and passing result after fix: <met | not met | unclear> - - Evidence: <brief proof from `debug.md`, test output, checks, behaviour, or missing verification> + - Evidence: <brief proof from `debug.md`, worker report, code, tests, diff, checks, behaviour, prompts, workflow rules, or missing verification> - Chosen fix hypothesis respected: <met | not met | unclear> - - Evidence: <brief proof from code, diff, checks, behaviour, or missing verification> + - Evidence: <brief proof from `debug.md`, worker report, code, tests, diff, checks, behaviour, prompts, workflow rules, or missing verification> - Verification sufficient for bug behaviour: <met | not met | unclear> - - Evidence: <brief proof from code, diff, checks, behaviour, or missing verification> + - Evidence: <brief proof from `debug.md`, worker report, code, tests, diff, checks, behaviour, prompts, workflow rules, or missing verification> <if findings, include this section> **Findings** -- [<high | medium | low>] <short finding title> +- [<critical | high | medium | low | nitpick>] <short finding title> - Location: <exact file/section/command when possible> - Issue: <what is wrong> - - Impact: <why this matters for correctness, diagnosis confidence, or verification> + - Impact: <why this matters for correctness, diagnosis confidence, verification, security, maintainability, or regression risk> + - Evidence: <specific evidence from `debug.md`, worker report, code, tests, diff, checks, behaviour, prompts, workflow rules, or missing verification> - Fix: <practical direction, not a full patch> </if findings, include this section> @@ -86,10 +105,31 @@ Use this exact format for your output. These rules are MANDATORY. -- Treat the diagnosis gate as required, not advisory. -- Reject speculative or symptom-only fixes; missing root-cause evidence; missing fail-then-pass proof or accepted no-test rationale; changes outside the chosen hypothesis; or permanent code changes outside the bug-worker subagent. -- Call out missing verification or contradictory evidence explicitly. -- MUST return exactly one `Status:` line with either `approved` or `rejected`. -- If `Status: rejected`, MUST include at least one finding. +- NEVER approve from the worker report alone; review `debug.md`, real code, tests, current diff, and check output. +- NEVER make code changes; review only. +- ENSURE every review criterion is evaluated as `met`, `not met`, or `unclear`, with evidence. +- RETURN exactly one `Status:` line with either `approved` or `rejected`. +- Status CAN be `approved` only when every criterion is `met`, diagnosis still holds, verification is met, and there are no blocking findings. +- Status MUST be `rejected` if any criterion, diagnosis, or verification item is `not met` or `unclear`. +- TREAT `critical`, `high`, `medium`, and `low` findings as blocking. +- TREAT `nitpick` findings as non-blocking only when every criterion, diagnosis, and verification item is met and no blocking findings exist. +- INCLUDE at least one actionable finding when using `rejected`. +- ORDER findings by severity, highest first, with `nitpick` findings last. - If rejected, say whether the result should reset back to diagnosis. +- If diagnosis, hypothesis fit, or verification is unclear or contradicted, use evidence-backed `Diagnosis Status`, `Verification Status`, and `Reset Guidance` to preserve the debug control-loop decision. +- ALWAYS follow the output structure and section order exactly as specified. + +## Completion Gate + +Do NOT output your response until ALL items are complete. + +- [ ] Current `debug.md` reviewed in full. +- [ ] Worker implementation report reviewed as context, not proof. +- [ ] Real implementation inspected in the repo, including relevant code, tests, current diff, and check output. +- [ ] Every review criterion evaluated with evidence. +- [ ] Diagnosis status and verification status evaluated with evidence. +- [ ] Findings categorised with the required severity rules. +- [ ] Reset guidance provided when diagnosis, hypothesis fit, or verification is unclear or contradicted. +- [ ] Approval decision set to `approved` or `rejected` according to criteria, diagnosis, verification, and finding severity rules. +- [ ] Output implementation review report in the exact format specified. ```` From 4d7ca271659b1b0de4a56f0348baece6a8d84087 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Sun, 10 May 2026 21:36:46 +0100 Subject: [PATCH 5/5] Bump version --- .codex-plugin/plugin.json | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 93d1e89..12b91f0 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "propulsion", - "version": "1.1.0", + "version": "1.1.1", "description": "Opinionated agentic coding workflow that guides software work from exploration and planning through execution and review.", "author": { "name": "Moon Pixels" diff --git a/package.json b/package.json index 7e04cf6..66c0d91 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "propulsion", - "version": "1.1.0", + "version": "1.1.1", "main": "./index.mjs", "exports": "./index.mjs", "scripts": {