Quick Fix — Lightweight Change Workflow
A finished quick fix is one commit on a branch that holds the change and a test that failed before it and passes after, with the full test suite, build and lint green. The workflow stays this short only because the change is small and its approach obvious; when either stops being true, hand over to the full workflow.
Working folder. Blueprint working files live under .agent-blueprint/ in the project root. Before the first write there, make sure .agent-blueprint/.gitignore exists and lists run/, team/, review-runs/, cache/ and .gitignore, so run state and the ignore file itself stay out of commits while plans and notes stay tracked.
Provenance record. Before any other work, run this as written from the project root: mkdir -p .agent-blueprint/run/provenance && date -u +'{"skill": "ab-quick-fix", "version": "4.2.1", "started_at": "%Y-%m-%dT%H:%M:%SZ", "helper_steps": []}' > .agent-blueprint/run/provenance/ab-quick-fix.json. It replaces any older record, and the Working folder step above has already made sure of .agent-blueprint/.gitignore. Each Helper step adds {step, path: helper|inline} to helper_steps. The record tells a run, and the smoke test, which skill ran and how; it is not a security control.
Step 1: Qualification Check
Before starting, confirm the change is quick: a bug fix with an obvious root cause, a typo, copy or config fix, a test for existing behavior, or a rename or minor refactor within one module, touching under three files. Hand over instead for:
- Three or more files: use the ab-build-pipeline skill (or ab-ship-pipeline for an autonomous run).
- A new public API, endpoint or schema, or a data-model change: it needs design first, with the ab-brainstorming skill.
- Auth, payments or data-migration code: always the full pipeline with review, never this skill, because a small-looking change there can do outsized harm.
- An unclear approach, or several options: use the ab-discuss or ab-brainstorming skill.
- A bug with a non-obvious root cause: use the ab-systematic-debugging skill first, and this skill once the cause is known and the fix is small.
If the change does not qualify, say so and switch to the skill named above. If it qualified but grows past these limits mid-fix, stop and switch to the ab-build-pipeline skill.
Step 2: Write a Failing Test
Use the ab-test-driven-development skill.
Write a test that describes the expected behavior before any implementation code. Run it: it should fail (red).
Step 3: Implement the Fix
Write the minimum code to make the test pass. Run the test: it should pass (green).
Step 4: Verify
Run the full test suite (not just your test), the build and the linter, with the commands in docs/context/CONVENTIONS.md or the project instructions file:
[test command]
[build command]
[lint command]
All three pass before you commit.
Step 5: Commit
Commit on a branch unless the user said otherwise; on the default branch, create one first (in no-commit mode, below, do neither). Stage only the files you changed, and follow the project's commit conventions:
git add [specific files]
git commit -m "[type](scope): [description]"
No-commit mode. If the user says not to commit, AGENT_BLUEPRINT_GIT_WRITABLE is 0, or .git is read-only, make no commits: leave changes in the working tree and add the intended message to .agent-blueprint/run/commit-msg.md. With AGENT_BLUEPRINT_GIT_WRITABLE=0, the ship runner commits after the session, so it is not for work the user wants uncommitted. Reviews use the working tree and untracked files against the merge base instead of a commit range.
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "It's quick, I'll skip the failing test" | Quick-fix without a test is a guess. The test is what makes the fix verifiable; skipping it means you can't tell if you fixed anything. |
| "The qualification check feels like overhead" | Misqualifying a complex change as ab-quick-fix is how two-file fixes balloon into 12-file regressions. The check is the cheapest insurance. |
| "Two files now, but I'm sure it'll stay small" | If you're sure, prove it: scope it, do it, commit. If scope creeps mid-fix, stop and switch to ab-build-pipeline. Don't backfill design after the fact. |
| "I'll skip lint — it's just style" | Lint catches structural issues alongside style. Quick-fix is short; lint is fast; run it. |
| "Trivial fix, I'll commit straight to main" | Quick-fix is fast, not unreviewed. Commit to a branch unless explicitly told otherwise. |