feat: improve skill workflow guidance

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "propulsion",
-    "version": "1.0.6",
+    "version": "1.1.0",
     "description": "Opinionated agentic coding workflow that guides software work from exploration and planning through execution and review.",
     "author": {
         "name": "Moon Pixels"

package.json

@@ -1,6 +1,6 @@
 {
     "name": "propulsion",
-    "version": "1.0.6",
+    "version": "1.1.0",
     "main": "./index.mjs",
     "exports": "./index.mjs",
     "scripts": {

skills/brainstorm/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: brainstorm
-# prettier-ignore
 description: Create an approved PRD through repo inspection and interrogation. Use when scope, UX, constraints, or success criteria are unclear, or when user needs a PRD.
 ---
 
@@ -10,43 +9,40 @@ Turn vague feature, UX, API, product-scope, or requirements work into an approve
 
 ## Prerequisites
 
-ALL prerequisites MUST be true before following this skill.
+ALL prerequisites MUST be satisfied BEFORE following this skill.
 
-- If an approved `docs/propulsion/.../prd.md` already exists for this work, STOP. Enter the `plan` skill.
+- If user provides an approved `docs/propulsion/.../prd.md`, STOP. Enter the `plan` skill.
 
 ## Instructions
 
 Follow these steps IN ORDER. Do NOT skip steps.
 
-1. Load `interrogate` skill to close blocking branches and reach shared understanding before PRD writing.
-2. If the request is too large, decompose it and explore only the first phase or subsystem.
-3. After all blocking branches are closed and brainstorming is complete, check for relevant non-Propulsion skills and load them before writing `prd.md`.
-4. Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` using the template in [references/prd-template.md](references/prd-template.md), including resolved decisions, project facts, and constraints from `interrogate`.
-5. Compare `prd.md` against the conversation for missing decisions, facts, constraints, requested behaviours, or success criteria; update `prd.md` before approval if relevant content is missing.
-6. Ask the user to review `prd.md`; treat only explicit approval, such as "approved" or "yes, proceed", as approval before entering `plan`.
+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).
+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.
 
 ## Rules
 
 These rules are MANDATORY.
 
-- MUST close every blocking branch before writing `prd.md`. Blocking branches include anything that would change scope, UX, architecture, sequencing, or success criteria.
-- BEFORE writing `prd.md`, 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.
+- ALWAYS use `interrogate` skill to reach a 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.
 - ENSURE the PRD includes ALL relevant decisions, even if they seem obvious or minor.
-- You CAN create supporting documents such as `docs/propulsion/.../research.md` or `docs/propulsion/.../diagrams.md` if needed, but the PRD must include all durable decisions.
-- DO include the supporting documents as implementation inputs in the PRD, but DO NOT rely on them for durable decisions.
-- DO NOT print the PRD, or other workflow artefacts in the chat, keep them in files.
-- If you cannot write files, STOP, ask the user to switch to write mode, then continue to write the PRD.
+- 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.
+- NEVER print the full PRD in the chat, ONLY write it to the file.
 
 ## Completion Gate
 
 Do NOT leave this skill until ALL items are complete.
 
-- [ ] Used `interrogate` skill to reach shared understanding and close every blocking branch.
-- [ ] `prd.md` written to `docs/propulsion/.../prd.md`.
-- [ ] `prd.md` sanity-checked against the conversation and updated if relevant content was missing.
-- [ ] User has explicitly approved `prd.md` after self-review.
+- [ ] Used `interrogate` skill to gather every last detail about the request.
+- [ ] Written PRD to `docs/propulsion/.../prd.md`.
+- [ ] Compared PRD against conversation and added any missing content.
+- [ ] User has explicitly approved `prd.md`.
 
 ## Next Steps
 

skills/brainstorm/references/prd-template.md

@@ -3,38 +3,59 @@
 Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` using this exact section order.
 
 ```md
-# <Feature Title>
+# <Feature Title> PRD
 
 ## Problem Statement
 
-State the user problem in user language.
+State the problem in user language.
+
+## Solution
+
+Describe the proposed behaviour end-to-end from the user's perspective.
 
 ## Goals
 
 - Goal 1
 - Goal 2
 
+## Non-Goals
+
+- Explicit non-goal 1
+- Explicit non-goal 2
+
 ## User Stories
 
-1. As a <actor>, I want <behaviour>, so that <benefit>
-2. As a <actor>, I want <behaviour>, so that <benefit>
+| ID     | User Story                                           |
+| ------ | ---------------------------------------------------- |
+| US-001 | As a <actor>, I want <behaviour>, so that <benefit>. |
+| US-002 | As a <actor>, I want <behaviour>, so that <benefit>. |
 
-## Solution
+## Functional Requirements
 
-Describe the proposed behaviour end-to-end from the user's perspective.
+| ID     | Requirement                                  |
+| ------ | -------------------------------------------- |
+| FR-001 | When <context>, the system must <behaviour>. |
+| FR-002 | The system must <behaviour> when <context>.  |
 
-## Implementation Inputs
+## Non-Functional Requirements
 
-- 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
+| ID      | Category    | Requirement                                   |
+| ------- | ----------- | --------------------------------------------- |
+| NFR-001 | Performance | <operation> must complete within <threshold>. |
+| NFR-002 | Security    | The system must <security requirement>.       |
 
 ## Implementation Decisions
 
 - Durable module or boundary decisions
 - Data shape or API contract decisions
 - Interaction rules that the `plan` skill should not re-litigate
 
+## 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
+
 ## Testing Decisions
 
 - What public behaviour matters
@@ -43,20 +64,29 @@ Describe the proposed behaviour end-to-end from the user's perspective.
 
 ## Out Of Scope
 
-- Explicit non-goals
+- Deferred idea
+- Thing that must not be implemented
 
-## Risks / Open Questions
+## Notes
 
-- Only non-blocking risks or future questions
+- Any further notes about the feature
 ```
 
 ## Rules
 
 These rules are MANDATORY.
 
-- Keep it product-facing.
-- Include durable decisions, not file paths or code.
-- Resolve blocking branches before writing.
-- Write the PRD to the correct path using the correct shape.
-- Use the first explored phase only if the request was decomposed.
-- Self-review for placeholders, contradictions, and scope drift before asking for approval.
+- 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.
+- DO create supporting documents with mermaid diagrams, data models, or other relevant artefacts if they help clarify the feature or implementation.

skills/commit/SKILL.md

@@ -9,7 +9,7 @@ Create exactly one local git commit from safe current changes and report the res
 
 ## Prerequisites
 
-ALL prerequisites MUST be true before following this skill.
+ALL prerequisites MUST be satisfied BEFORE following this skill.
 
 - The current directory is inside a git repository with a writable index.
 

skills/debug/SKILL.md

@@ -1,61 +1,66 @@
 ---
 name: debug
-# prettier-ignore
-description: Handle concrete bug reports through direct intake, reproduce, diagnose, TDD-fix, verify, reset, and escalate loops. Use when failures need repair.
+description: Handle concrete failures through intake, diagnosis, one-hypothesis fixes, review, reset, and escalation. Use when bugs or failures need repair.
 ---
 
 # Debug
 
-Use when a concrete failure or bug report needs diagnosis and repair.
+Diagnose concrete failures before dispatching one evidence-backed fix loop.
 
 ## Prerequisites
 
-ALL prerequisites MUST be true before following this skill.
+ALL prerequisites MUST be satisfied BEFORE following this skill.
 
-- The work is a bug, regression, crash, incorrect output, flaky behaviour, or other concrete failure.
-- If the work is feature-shaped or expected behaviour is intentionally being designed, STOP. Load `brainstorm`.
+- The request is a concrete failure: bug, regression, crash, failing test/build, incorrect output, flaky behaviour, or runtime error.
+- If the request is feature-shaped, product-scope work, expected-behaviour design, refactor, optimisation, or enhancement, STOP and load `brainstorm`.
 
 ## Instructions
 
 Follow these steps IN ORDER. Do NOT skip steps.
 
-1. Create or resume `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` using [references/debug-template.md](references/debug-template.md).
-2. Load `interrogate` skill for missing user-answerable intake: report provenance, expected behaviour, actual behaviour, impact, environment, reproduction, and questions answered.
-3. Record intake answers and resolved decisions from `interrogate` in `debug.md`; if expected behaviour is unknowable, stay in `debug` and ask or block.
-4. Complete targeted codebase exploration in `debug.md` before reproduction, diagnosis, or fix work: relevant files, existing tests, commands, logs, ownership, and candidate boundaries only.
-5. Reproduce, reduce, isolate, diagnose, reset, and escalate with [references/investigation-loop.md](references/investigation-loop.md).
-6. Do not allow production-code changes until `debug.md` contains a grounded diagnosis, supporting evidence, fix constraints, and one chosen fix hypothesis.
-7. Start a fresh bug-worker subagent with [references/bug-worker-prompt.md](references/bug-worker-prompt.md), then review with [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md).
-8. If review rejects the fix, send findings back with [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md). Repeat until approved, reset when evidence contradicts the diagnosis, or reassess architecture and patterns before escalating after 3 failed fix loops.
-9. If the fix is verified and approved, record closure in `debug.md` and finish.
+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`.
+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`.
+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.
+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.
+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
 
 These rules are MANDATORY.
 
-- MUST keep `debug.md` current from direct entry or resumed entry through closure.
-- MUST complete intake for expected behaviour, actual behaviour, impact, environment, and reproduction before broad code inspection or fix work.
-- MUST record `interrogate` intake answers and resolved decisions in `debug.md`.
-- MUST record targeted codebase exploration before reproduction, diagnosis, or fix work.
-- MUST stabilise reproduction, reduce the failing case, and isolate the first bad boundary or divergence before choosing a fix.
-- NEVER edit production code in the main `debug` stage.
-- EVERY fix attempt MUST start with a failing regression test and target one fix hypothesis.
-- MUST record each failed hypothesis, diagnostic edit, fix attempt, review outcome, reset, escalation, and closure in `debug.md`.
+- 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.
+- 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.
 
 ## Completion Gate
 
 Do NOT leave this skill until ALL items are complete.
 
-- [ ] `debug.md` exists at `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` and was created or resumed on entry.
-- [ ] Intake, `interrogate` answers and resolved decisions, targeted codebase exploration, reproduction, reduction, evidence, ranked hypotheses, experiments, diagnosis gate, fix attempts, review outcomes, verification, and closure are recorded in `debug.md`.
-- [ ] The bug is either closed with verified evidence or escalated after architecture and pattern reassessment following 3 failed fix loops.
+- [ ] `debug.md` exists or is resumed at `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md`.
+- [ ] Intake, user-answerable `interrogate` decisions if any, targeted exploration, reproduction or no-repro attempts, full error reading, reduction, evidence, hypotheses, diagnosis gate, fix loops, reviews, resets, and verification are recorded.
+- [ ] Outcome is one of: fixed and verified; blocked on missing intake; no-repro with documented attempts; reset to diagnosis with contradicted evidence; review-rejected and returned to worker; escalated after 3 failed loops plus architecture and pattern reassessment.
+
+## Next Steps
+
+Once the completion gate is fully checked:
+
+- Return a concise status with the `debug.md` path, final outcome, checks run, and any user decision needed.
 
 ## References
 
 Use these references when you need detail.
 
-- [references/debug-template.md](references/debug-template.md) - Living `debug.md` template for the full bug dossier.
-- [references/investigation-loop.md](references/investigation-loop.md) - Core bug loop for reproduce, reduce, isolate, diagnose, reset, and escalate.
+- [references/debug-template.md](references/debug-template.md) - Living `debug.md` template for the bug dossier.
+- [references/investigation-loop.md](references/investigation-loop.md) - Evidence-first reproduce, reduce, isolate, diagnose, reset, and escalate loop.
 - [references/bug-worker-prompt.md](references/bug-worker-prompt.md) - Prompt template for one diagnosis-gated TDD fix attempt.
 - [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md) - Prompt template for independent review of one bug fix attempt.
-- [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md) - Prompt template for feeding review findings back into the active bug fix attempt.
+- [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md) - Prompt template for returning review findings to the active worker.