From 510d47c94e4a70a74881e9c1d382d1a998d5f5e4 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Thu, 9 Apr 2026 19:33:08 -0400 Subject: [PATCH 1/3] Convert bugfix and feature commands to thin wrappers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR 3 of deterministic workflow conversion. Converts bugfix and feature command files to thin wrappers that delegate to existing YAML workflows. YAML workflows (bugfix.yml, feature.yml) unchanged — they already have rich triage fast-paths, scratchpad integration, parallel reviews, and proper loop gates. Note: the spec's `expect` field and `branch` construct require engine changes (separate repo). Filed as future engine enhancement. Commands: 2 files, -173 lines --- commands/bugfix.md | 93 +++++++--------------------------- commands/feature.md | 119 ++++++++------------------------------------ 2 files changed, 39 insertions(+), 173 deletions(-) diff --git a/commands/bugfix.md b/commands/bugfix.md index ca541f6..bd7dda7 100644 --- a/commands/bugfix.md +++ b/commands/bugfix.md @@ -2,88 +2,31 @@ description: Full lifecycle bug fix — reproduce, diagnose, fix, regression test, verify. --- -# Bug Fix Workflow +# Bug Fix -Complete bug fix lifecycle: reproduce → diagnose root cause → fix → regression test → verify. +Deterministic bug fix lifecycle: triage → reproduce → diagnose → fix → regression test → verify. -## Budget & Early Exit +## Invoke -- **Token budget:** ~300k tokens. -- **Early exit:** Stop the test loop when all tests pass. Don't iterate further. -- **Stuck detection:** If 3 consecutive fix attempts fail, stop and report. See the `stuck` skill. - -## Step 1: Reproduce - -``` -Bug report: {user's input} - -Reproduce the issue: -1. Find the relevant code -2. Understand the expected vs actual behavior -3. Identify a minimal reproduction path -4. Confirm the bug exists (run the failing case if possible) -``` - -## Step 2: Diagnose - -``` -Trace the root cause using the reproduction from Step 1. -Read the code path, check assumptions, examine edge cases. -Determine exactly WHY this happens, not just WHERE. - -Propose a specific fix with reasoning. -``` - -## Step 3: Fix - -``` -Implement the fix based on the diagnosis. -Keep changes minimal — only touch what's needed to resolve the root cause. -Don't refactor surrounding code. ``` - -## Step 4: Regression Test - +devkit workflow run bugfix "{bug_description}" ``` -Write a regression test that: -1. Would have caught this bug before the fix -2. Verifies the fix works -3. Covers the edge case that triggered the bug -``` - -## Step 5: Run Tests - -```bash -# Run the full test suite including the new regression test -# Auto-detect test command from project config -``` - -If tests fail, fix them. Determine if the test or the code is wrong. Loop up to 5 times until all pass. -## Step 6: Summary +If `devkit workflow` is not available, follow this manually: -``` -## Bug -What was reported and how it was reproduced. - -## Root Cause -What was actually wrong and why. - -## Fix -What was changed and why. - -## Regression Test -What test was added to prevent recurrence. - -## Status -Test suite status. Ready to commit or remaining concerns. -``` +1. **Triage** — Classify as TRIVIAL / NORMAL / COMPLEX. Trivial bugs skip to quick-fix path. +2. **Reproduce** — Read relevant code, understand expected vs actual, identify minimal reproduction path +3. **Diagnose** — Trace root cause (WHY, not just WHERE); propose specific fix with reasoning +4. **Fix** — Implement minimal fix; don't refactor surrounding code +5. **Regression test** — Write a test that would have caught this bug; verify it fails without the fix and passes with it +6. **Run tests** — Run full test suite including new regression test +7. **Fix test failures** — If tests fail, determine if bug is in test or code; fix and re-run (loop max 5) +8. **Summary** — Report bug, root cause, fix, regression test, and test suite status ## Rules -- Reproduce before diagnosing — confirm the bug exists first -- Root cause, not symptoms — understand WHY, not just WHERE -- Minimal fix — don't refactor, don't clean up, just fix the bug -- Regression test required — every fix must include a test that would have caught it -- All tests must pass before reporting done -- Loop on test failures up to 5 times +- Reproduce before diagnosing — don't guess at root causes +- Minimal changes only — fix the bug, don't refactor +- Always write a regression test +- Tests must pass before declaring fixed +- Use scratchpad (`.devkit/scratchpads/current.md`) to track attempts across iterations diff --git a/commands/feature.md b/commands/feature.md index c9fc738..fc6be20 100644 --- a/commands/feature.md +++ b/commands/feature.md @@ -2,111 +2,34 @@ description: Full lifecycle feature development — brainstorm, plan, implement, test, lint, review. --- -# Feature Workflow +# Feature -Complete feature lifecycle: brainstorm → plan → implement → test → lint → review → report. +Deterministic feature lifecycle: triage → brainstorm → plan → implement → test → lint → review → report. -## Step 1: Brainstorm +## Invoke -Identify the feature's relevant domains (auth, API, database, UI, etc. — features often span multiple) and read each matching section from `references/domain-probes.md` to surface gray areas. If no section matches, skip domain probing. Use the probes to ask targeted questions via `AskUserQuestion` — only for genuinely ambiguous decisions, not obvious ones. Skip probing if the user's input already resolves the gray areas. - -``` -Feature: {user's input} - -Think through the design: -- What components need to change? -- What's the simplest approach that works? -- What are the risks or unknowns? -- Are there edge cases to handle upfront? -- What gray areas need user input before planning? (use domain probes) - -Produce a short design summary with decisions locked. Don't write code yet. -``` - -## Step 2: Plan - -``` -Based on the design from Step 1, create an implementation plan -as a numbered todo list. - -Each item should be a single, testable change. -Order by dependency — do foundations first. -Include a final item for writing tests. ``` - -## Step 3: Implement - -``` -Execute the next incomplete todo from the plan. -Write the code, verify it works, then mark it done. -Keep changes small and focused. -``` - -Loop until all todos are complete. Max 20 iterations. - -## Step 4: Generate Tests - -``` -Generate tests covering: -- Happy path for each new public function/endpoint -- Edge cases and error conditions -- Integration between new and existing code - -Use the project's existing test framework. -Place tests in the project's standard test location. +devkit workflow run feature "{feature_description}" ``` -## Step 5: Run Tests +If `devkit workflow` is not available, follow this manually: -Run the full test suite (not just the new tests). If tests fail, fix them — determine if the bug is in the test or the implementation. Loop up to 8 times until all pass. - -## Step 6: Lint - -Run the project's linter on changed files. If there are violations, fix them without changing code behavior. Loop up to 4 times until clean. - -## Budget - -- **Token budget:** ~500k tokens. Features are the most expensive workflow. -- If approaching budget, skip the review step and report what was completed. - -## Step 7: Review - -**[PARALLEL]** Spawn the `reviewer` agent to review all changes (can run concurrently with any remaining lint fixes): - -``` -Task: Review all changes made in this feature session. -Agent: reviewer -Context: - - Design intent from brainstorm step - - Check for: correctness, security issues, missing error handling, - performance problems, violations of original design intent - - Be specific — reference files and line numbers -``` - -## Step 8: Final Report - -``` -## What was built -Design summary from brainstorm. - -## Implementation -Brief description of what was implemented and how many steps it took. - -## Test coverage -Test results summary. - -## Review findings -Issues found during review. - -## Status -Ready to commit, or list remaining issues. -``` +1. **Triage** — Classify as TINY / SMALL / MEDIUM / LARGE. Tiny changes skip to quick-fix path. +2. **Brainstorm** — Explore codebase, identify patterns and conventions, propose 2-3 design approaches with trade-offs +3. **Plan** — Create numbered implementation todo list ordered by dependency +4. **Implement** — Execute one todo at a time; small focused changes; track progress in scratchpad (loop max 20) +5. **Generate tests** — Write tests for the new feature covering happy path, edge cases, and error conditions +6. **Run tests** — Run full test suite +7. **Fix test failures** — Fix any failures, determine if bug is in test or implementation (loop max 8) +8. **Lint** — Run linter on changed files; fix violations if any (loop max 5) +9. **Review** — Parallel smart + fast review of all changes +10. **Final report** — Summary of what was built, test coverage, review findings, and status ## Rules -- Design before code — brainstorm and plan first, implement second -- One todo at a time — finish each step before starting the next -- Tests are not optional — every feature gets tests -- Lint is not optional — clean code before review -- Review before done — catch issues before they're committed -- Loop on failures — don't give up after one test failure +- Triage honestly — most changes are smaller than they seem +- Design before implementing — don't jump to code +- One todo per iteration — keep changes small and focused +- Tests must pass before review +- Lint must be clean before review +- Use scratchpad (`.devkit/scratchpads/current.md`) to track progress across iterations From 8e41eb47d895cbb181343ff39438ae8cdf51e1ef Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Thu, 9 Apr 2026 19:34:47 -0400 Subject: [PATCH 2/3] Fix feature.md review findings: brainstorm description, lint max, SMALL skip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Brainstorm step: align with actual YAML prompt (design summary, not 2-3 approaches) - Lint loop: fix max 5 → 4 to match workflow - Add note that SMALL scope skips brainstorm step --- commands/feature.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/commands/feature.md b/commands/feature.md index fc6be20..50f03d9 100644 --- a/commands/feature.md +++ b/commands/feature.md @@ -15,13 +15,13 @@ devkit workflow run feature "{feature_description}" If `devkit workflow` is not available, follow this manually: 1. **Triage** — Classify as TINY / SMALL / MEDIUM / LARGE. Tiny changes skip to quick-fix path. -2. **Brainstorm** — Explore codebase, identify patterns and conventions, propose 2-3 design approaches with trade-offs +2. **Brainstorm** — Think through design: what components change, simplest approach, risks, edge cases. Produce a short design summary. (SMALL scope skips this step and goes directly to Plan.) 3. **Plan** — Create numbered implementation todo list ordered by dependency 4. **Implement** — Execute one todo at a time; small focused changes; track progress in scratchpad (loop max 20) 5. **Generate tests** — Write tests for the new feature covering happy path, edge cases, and error conditions 6. **Run tests** — Run full test suite 7. **Fix test failures** — Fix any failures, determine if bug is in test or implementation (loop max 8) -8. **Lint** — Run linter on changed files; fix violations if any (loop max 5) +8. **Lint** — Run linter on changed files; fix violations if any (loop max 4) 9. **Review** — Parallel smart + fast review of all changes 10. **Final report** — Summary of what was built, test coverage, review findings, and status From 8ba542896b1750e4eb53310f80400a02b7004c33 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Thu, 9 Apr 2026 19:35:36 -0400 Subject: [PATCH 3/3] Add scratchpad guidance to bugfix fallback steps 3 and 7 --- commands/bugfix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/commands/bugfix.md b/commands/bugfix.md index bd7dda7..0d7f51e 100644 --- a/commands/bugfix.md +++ b/commands/bugfix.md @@ -16,11 +16,11 @@ If `devkit workflow` is not available, follow this manually: 1. **Triage** — Classify as TRIVIAL / NORMAL / COMPLEX. Trivial bugs skip to quick-fix path. 2. **Reproduce** — Read relevant code, understand expected vs actual, identify minimal reproduction path -3. **Diagnose** — Trace root cause (WHY, not just WHERE); propose specific fix with reasoning +3. **Diagnose** — Check scratchpad for previous attempts; trace root cause (WHY, not just WHERE); propose specific fix with reasoning; append diagnosis to scratchpad 4. **Fix** — Implement minimal fix; don't refactor surrounding code 5. **Regression test** — Write a test that would have caught this bug; verify it fails without the fix and passes with it 6. **Run tests** — Run full test suite including new regression test -7. **Fix test failures** — If tests fail, determine if bug is in test or code; fix and re-run (loop max 5) +7. **Fix test failures** — If tests fail, check scratchpad for what was tried; determine if bug is in test or code; fix and re-run; append result to scratchpad (loop max 5) 8. **Summary** — Report bug, root cause, fix, regression test, and test suite status ## Rules