speckit-bug-fix
Apply the remediation from a bug assessment and record what was changed
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- speckit-bug-fix
- metadata
- { "author": "github-spec-kit", "source": "bug:commands/speckit.bug.fix.md" }
- description
- Apply the remediation from a bug assessment and record what was changed
- compatibility
- Requires spec-kit project structure with .specify/ directory
03 SKILL.md 正文
Fix Bug
Apply the remediation that was proposed by /speckit-bug-assess and record the changes in a fix report at .specify/bugs/<slug>/fix.md. This command is only valid after an assessment exists for the given slug. Pass --branch (or --worktree) to isolate the fix on its own git branch before editing, mirroring how /speckit-specify isolates feature work.
User Input
$ARGUMENTS
The user input should identify the bug to fix. Accept any of:
slug=<bug-slug>or--slug <bug-slug>or just a bare slug-like token.- A path that contains the slug (e.g.
.specify/bugs/login-timeout/). - Branch isolation (optional):
branch/--branchcreates a fix branch (<prefix>/<slug>) first;worktree/--worktreecreates a git worktree instead. See Optional — isolate the fix on a branch below. - Nothing — fall back to context (see below).
Slug Resolution
Resolve BUG_SLUG in this order, stopping at the first match:
- Explicit user input — a slug passed in
$ARGUMENTS(any of the forms above). - Conversation context — if the current session has just run
/speckit-bug-assess, the slug it reported is the working slug. Reuse it without re-prompting. Confirm it by checking that.specify/bugs/<slug>/assessment.mdexists; if it does not, fall through. - Single candidate on disk — list
.specify/bugs/*/assessment.md. If exactly one matchingassessment.mdis found, use the slug from its parent directory. - Disambiguate:
- Interactive mode: ask the user which bug to fix and list the candidates.
- Automated mode: stop with an error listing the candidates. Do not guess.
Once resolved, set BUG_SLUG and BUG_DIR = .specify/bugs/<BUG_SLUG>, and briefly state in your reply which resolution path was used (explicit / from context / single candidate / asked).
Prerequisites
BUG_DIR/assessment.mdMUST exist. If it does not, stop and instruct the user to run/speckit-bug-assessfirst.- If
BUG_DIR/fix.mdalready exists, ask the user whether to overwrite it before continuing (interactive mode) or refuse (automated mode). - Read
BUG_DIR/assessment.mdin full. Treat its Proposed Remediation, Files likely to change, Tests to add or update, and Risks & Considerations sections as the contract for this command.
TDD mode (when tdd_enabled: true in bug-config.yml)
When the bug extension's tdd_enabled config is true (the default), fix the bug
through the TDD extension's red-green-refactor loop instead of editing code directly.
This mirrors how spec-whole drives a feature — the "feature" here is the bug:
- Ensure the TDD stack profile exists — if
.specify/memory/tdd-profile.mdis missing, run/speckit.tdd.setupfirst (every other TDD command requires it). - Synthesize the bug spec — write
BUG_DIR/spec.mdfromassessment.md: the required (fixed) behavior becomes the acceptance criteria, and the assessment's reproduction steps become the failing-test scenario. This is the TDD spec source. - Pin the bug as the TDD feature — set
.specify/feature.jsonsofeature_directorypoints atBUG_DIR(e.g..specify/bugs/<slug>). Everything downstream (tdd.plan,tdd.run,tdd.verify) then operates on this directory. - Plan the tests — run
/speckit.tdd.planto deriveBUG_DIR/tdd/test-list.md. If noplan.mdexists inBUG_DIR, usetdd.plan outer-only. - Drive the loop — run
/speckit.tdd.run all. It writes the failing reproduction test, proves it RED, applies the minimal fix, proves it GREEN, refactors while green, and logs evidence inBUG_DIR/tdd/cycle-log.md. - Implement non-behavior work — run
/speckit.implementfor any scaffolding, config, or wiring tasks the loop left for it. - Write the fix report (Execution step 4), referencing the
tdd/artifacts.
In TDD mode the "Apply the remediation" step below is performed by tdd.run, not by
hand — do not pre-write the implementation before the test is red.
Execution
- Confirm the plan
- Restate, in 3–6 bullets, what you are about to change and where, based on the assessment.
- If the assessment's verdict is
invalid, stop — there is nothing to fix. Tell the user and exit. - If the verdict is
likely valid, needs reproductionand there are unresolved[NEEDS CLARIFICATION]items, flag them and ask the user whether to proceed in interactive mode, or stop in automated mode.
Optional — isolate the fix on a branch
By default the fix is applied to the current branch. To match how /speckit-specify isolates feature work, you may ask bug.fix to create a dedicated branch (or git worktree) first:
- Parse the user input for
branch/--branch/worktree/--worktree(orbranch=true/worktree=true). These are mutually exclusive; prefer--branchunless the user explicitly asks for a worktree. - Determine the branch name
<prefix>/<BUG_SLUG>, where<prefix>comes from.specify/extensions/bug/bug-config.yml(branch_prefix, defaultfix). Example:fix/login-timeout. If a branch with that name already exists, stop and ask the user how to proceed (reuse it, choose another name, or skip isolation). - Branch mode (
--branch): rungit checkout -b <prefix>/<BUG_SLUG>from the current branch (assumed clean or committed). - Worktree mode (
--worktree): rungit worktree add ../<repo>-<BUG_SLUG> -b <prefix>/<BUG_SLUG>so the fix lives in a separate working directory; then continue operations there. - If Git is unavailable or the directory is not a Git repository, skip isolation with a warning and apply the fix on the current branch.
- State which mode was used in your reply; all subsequent edits happen on that branch/worktree.
-
Apply the remediation
- TDD mode: if
tdd_enabledistrue, you already drove the fix viatdd.runin the TDD-mode section above. Skip to step 3 and step 4, and reference thetdd/artifacts (test-list, cycle-log, verification) in the report. - Make the code changes described by the preferred remediation. Stay within the files listed by the assessment unless newly discovered evidence requires expanding scope (in which case, log the expansion explicitly in the report).
- Add or update the tests called out in the assessment so the bug cannot regress silently.
- Keep the change minimal — do not refactor unrelated code, do not introduce dependencies that the assessment did not call for.
- If you discover the assessment was wrong (the proposed fix does not work, the root cause is elsewhere), STOP modifying code, document the new finding in the fix report under Deviations from Assessment, and recommend re-running
/speckit-bug-assess.
- TDD mode: if
-
Run local checks
- If the project has obvious test commands (e.g.,
pytest,npm test,cargo test), run the tests that exercise the changed paths. Capture pass/fail and key output. - Do not run destructive or network-dependent suites without the user's consent.
- If the project has obvious test commands (e.g.,
-
Write the fix report
Write to
BUG_DIR/fix.mdusing this structure:# Bug Fix: <short title> - **Slug**: <BUG_SLUG> - **Fixed**: <ISO 8601 date> - **Assessment**: ./assessment.md - **Status**: applied | partial | not-applied - **TDD artifacts**: ./tdd/test-list.md, ./tdd/cycle-log.md, ./tdd/verification.md (present only when the fix ran in TDD mode) ## Summary <One or two sentences describing what was changed and why.> ## Changes | File | Change | Notes | |------|--------|-------| | `path/to/file.py` | <added / modified / removed> | <short note> | | `path/to/test_file.py` | added test | <short note> | ## Diff Highlights (optional) <Short, illustrative snippets of the most important hunks — not a full diff dump.> ## Tests Added or Updated - `path/to/test_file.py::test_name` — <what it pins down> ## Local Verification - Commands run: `<command>` → <result, brief> - Manual checks: <what was verified by hand, if anything> ## Deviations from Assessment <Empty if none. Otherwise, list any places where the actual fix departed from the proposed remediation and why.> ## Follow-ups - <suggested cleanup, monitoring, doc update, etc.> -
Report back with:
- The slug and
BUG_DIR/fix.mdpath. - The status (
applied,partial,not-applied). - Which branch/worktree the fix was applied to (or "current branch" if isolation was not used).
- The next suggested step(s), in order:
/speckit-bug-pr slug=<BUG_SLUG>(open a PR from the fix branch, linking the issue).- Then:
/speckit-bug-test slug=<BUG_SLUG>(validate the fix). In TDD mode this runstdd.verifyagainst the bug directory and reports its verdict.
- The slug and
Guardrails
- Never modify files outside the project workspace.
- Never edit
assessment.md— it is the contract you are working against. Record disagreements infix.mdunder Deviations from Assessment. - Never delete files unless the assessment explicitly required it.
- Never overwrite an existing
fix.mdwithout confirmation.
04 同仓库更多 Skills
speckit-tdd-verify
Audit TDD discipline by delegating to zfa tdd verify (mutation testing, evidence integrity); the LLM interprets the verdict and drives remediation
speckit-tdd-setup
Detect the test stack and write .specify/memory/tdd-profile.md; zuraffa-wired projects record zfa commands as the engine
speckit-tdd-run
Drive the red-green-refactor loop by delegating to zfa tdd run (deterministic engine); the LLM handles only honest stops — fixing genuine reds and remediation — never re-driving what zfa drives
speckit-tdd-plan
Derive the feature's test list by delegating to zfa tdd plan (deterministic engine); falls back to LLM-guided derivation only when zfa is unavailable
speckit-spec-stats-runs
On-demand execution — reads verified suite command from .specify/memory/tdd-profile.md, runs it for selected specs (--all, spec id/slug, or default active feature), captures pass/fail + duration + tail, appends run record to .specify/stats/runs.json, refreshes dashboard health column
speckit-spec-stats-report
Main generator — scans all specs/*/, derives per-feature stage, task progress, health, last updated; when the TDD extension is installed, adds a deep TDD table (acceptance/unit/characterization counts, DONE, loop mode, tasks.md state); renders dashboard to configurable output path and writes .specify/stats/stats.json snapshot