Skip to content

PR 3: Convert bugfix and feature commands to thin wrappers #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
5uck1ess merged 3 commits into from
Apr 9, 2026
Merged

PR 3: Convert bugfix and feature commands to thin wrappers #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
510d47c
Convert bugfix and feature commands to thin wrappers
5uck1ess Apr 9, 2026
8e41eb4
Fix feature.md review findings: brainstorm description, lint max, SMA…
5uck1ess Apr 9, 2026
8ba5428
Add scratchpad guidance to bugfix fallback steps 3 and 7
5uck1ess Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 18 additions & 75 deletions commands/bugfix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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** — 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, 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

- 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
119 changes: 21 additions & 98 deletions commands/feature.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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** — 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 4)
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
Loading