القائمة
Test-driven bug fix methodology — loaded by the bug-fix pipeline to enforce reproduce-first, red-green discipline when fixing defects
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Keep a Changelog methodology — loaded by the ship phase to update CHANGELOG.md with user-facing changes, filtering out internal-only commits
Generator-evaluator separation and review methodology — loaded by review agents to enforce fresh-context review discipline, Conventional Comments format, and gate verdicts
Architecture Decision Record creation and management — loaded by planner and orchestrator when significant technical decisions need to be recorded with context and consequences
Adversarially review a technical design document with fresh context before the human gate. Dispatches the built-in `general-purpose` subagent (clean context, no shared history with the design-author) against `docs/plans/<id>/design.md` and presents its verdict — APPROVE, REQUEST CHANGES, or COMMENT. Optional, not part of the QRSPI pipeline. Trigger on "review the design doc", "audit design.md", "is this design ready", or `/eng-design-doc-review`.
Git commit discipline methodology — loaded by the ship phase to produce well-formed commits following conventional commits format, the 50/72 rule, and atomic commit principles
Optional PRD methodology — loaded by the questioner agent when a feature request is vague or complex enough to warrant a structured product spec alongside task.md. Produces a PRD artifact that downstream design-author work can ground decisions in.
| name | test-driven-bug-fix |
| description | Test-driven bug fix methodology — loaded by the bug-fix pipeline to enforce reproduce-first, red-green discipline when fixing defects |
| user-invocable | false |
A bug without a failing test is an unverified assumption. A bug fixed without a failing test may be fixed correctly this time, but has no protection against regression. The test-driven bug fix discipline ensures that every fix is:
Before reproducing, classify the failure into one of four buckets:
| Bucket | Symptom | Action |
|---|---|---|
| Product | Real defect in the code under test | Continue with the four-step discipline below |
| Test impl | Test wrong; behavior correct | File a separate test-fix; do NOT change production code to satisfy a bad test |
| Infra | CI environment, DB, network, container | Fix the env; do not encode the env-fix as a test |
| Tooling | Test runner / build system | Fix the tool; the bug is not in the product |
Intermittent failures are not a fifth bucket — they belong in one of the
four above. Quarantining a test as "flaky" without classifying the failure
hides the very intermittent product bug that the test surfaced. The
conditions that make a test flaky are frequently the conditions that
trigger the bug. Reproduce deterministically before fixing — see
skills/systematic-debugging/SKILL.md. When the failure is non-obvious,
drill the causal chain to its root first via the Root Cause Analysis
(5 Whys) subsection of skills/systematic-debugging/SKILL.md before
proposing a fix.
Follow
skills/progress-tracking/SKILL.md: when this procedure has two or more steps, seed one todo item per step before starting and mark each complete as you go.
Before writing any code, reproduce the bug. Understanding exactly when and why the bug occurs is the prerequisite for everything that follows.
Do not hypothesize a fix during this step. Observe first.
Reproduction is complete when you can reliably trigger the bug on demand.
Write a test that:
Name the test to document the bug scenario: test_returns_error_when_token_is_expired,
not test_bug_123 or test_fix.
Run the test suite and confirm:
This is the "Red" state. Do not proceed until the test fails correctly.
Apply the smallest change that makes the failing test pass.
This is the "Green" state. The targeted test passes, all other tests pass.
After the fix:
Run the full test suite. Every existing test must pass. If any test now fails that passed before, the fix introduced a regression — undo and investigate.
Re-run the reproduction case. Confirm that the original bug no longer occurs with the original inputs.
Check for related instances. If the root cause is a pattern (e.g., missing null check), search the codebase for the same pattern. File issues for related instances — do not fix them in this commit.
Review the minimal fix with a mutation check. Temporarily revert one line of the fix and re-run the new test. It must go red again. If it still passes, the test does not exercise the fix — strengthen the assertion or the reproduction inputs. This guards against fixes that hide the symptom without addressing the root cause, and against tests that drift away from the bug.
Each step produces a commit:
test: reproduce <bug description> with failing test
Adds a test that fails due to the bug described in <issue reference>.
The test will pass once the fix is applied.
fix: <minimal description of the fix>
Fixes the root cause identified in the preceding test commit.
All tests now pass including the new reproduction test.
Closes #<issue>
Keeping the test commit and fix commit separate makes the intention clear: the test proves the bug existed, the fix makes it go away.