feat: add `/speckit.fix` command and fix-log template by omgbwa-yasse · Pull Request #2033 · github/spec-kit

omgbwa-yasse · 2026-03-31T16:07:10Z

Summary

This PR introduces the /speckit.fix command and its associated fix-log template to the Spec Kit workflow.

What was added

`templates/commands/fix.md` — New `/speckit.fix` command

A surgical error-correction agent that fits into the existing Spec-Driven Development lifecycle. It is activated by:

A screenshot of an error (UI, terminal, browser, IDE)
A pasted log block or error message (TypeError, 500, FAILED, ModuleNotFoundError, …)
A link or path to a broken file

The command follows a strict 5-phase workflow:

Extract — identify the verbatim error and its origin file
Diagnose — cross-reference with spec.md, plan.md, tasks.md, and constitution.md
Fix or escalate — apply a surgical, targeted fix, or escalate to /speckit.specify if the root cause is a spec gap
Establish invariants — declare what must never break again + edge cases explicitly not covered
Log — prepend a FIX-NNN entry to specs/[###-feature-name]/fix.md

The command is distributed to all supported agents via the standard template pipeline ($ARGUMENTS placeholder, {SCRIPT} path).

`templates/fix-template.md` — Fix-log template

Created once per feature on first correction. Each new fix entry is prepended (newest first). Each entry contains:

Verbatim error block
Metadata table: error type, detection location, root cause, impacted components
Files modified
Invariants established (INVARIANT: prefix)
Edge cases explicitly not covered (EDGE CASE: prefix)
Follow-up commands: /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement

`tests/test_fix_feature.py` — 39 tests (all passing)

Four test classes covering:

Class	Tests
`TestFixCommandFrontmatter`	YAML validity, description field, script paths, `--json`/`-Json` flags
`TestFixCommandBody`	`$ARGUMENTS`, all 9 workflow commands, diagnosis block, escalation guard, 5 phases, log reference, `{SCRIPT}`, no TOML leak
`TestFixTemplate`	`FIX-NNN` header pattern, metadata rows, 4 required sections, `INVARIANT:`/`EDGE CASE:` prefixes, follow-up commands, ordering comment
`TestFixCommandBundleInclusion`	`fix` in template stems, `fix-template.md` in `pyproject.toml`, command file exists

`pyproject.toml` — updated

templates/fix-template.md added to the hatch bundle so the file ships with the package and is available offline.

Design principles followed

No vibe-coding — the agent reads plan.md before writing any line
Surgical fixes only — one targeted change per FIX-NNN entry, no refactoring
Escalation path — if the root cause is a missing or wrong spec, the agent escalates to /speckit.specify instead of guessing
Consistent with existing agents — uses $ARGUMENTS (Markdown agents) placeholder, same frontmatter schema as analyze.md, plan.md, etc.
Newest-first log — makes recent history immediately visible without scrolling

Testing

pytest tests/test_fix_feature.py -v
# 39 passed, 0 failed

- Add templates/commands/fix.md: surgical error correction agent command - Add templates/fix-template.md: fix log template (FIX-NNN entries, newest first) - Update pyproject.toml: bundle fix-template.md in package data - Add tests/test_fix_feature.py: 39 tests covering frontmatter, body, template structure, and bundle inclusion

mnriem · 2026-03-31T16:11:42Z

Please deliver this as an extension. See https://github.com/github/spec-kit/tree/main/extensions for the information on how to develop an extension. And see any of the listed community extensions as examples at https://github.com/github/spec-kit?tab=readme-ov-file#-community-extensions

Copilot

Pull request overview

Adds a new /speckit.fix command template plus a standardized fix-log template to integrate “surgical corrections” into the Spec Kit workflow, with accompanying tests and packaging updates.

Changes:

Introduce templates/commands/fix.md defining a 5-phase error-correction workflow and escalation path.
Add templates/fix-template.md as the scaffold for per-feature fix.md logs (newest-first entries).
Add a new pytest suite validating the command/template invariants and ensure fix-template.md is bundled in the wheel via pyproject.toml.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
`templates/commands/fix.md`	New `/speckit.fix` command template (workflow + scripts/frontmatter).
`templates/fix-template.md`	New fix-log scaffold to be copied into `specs/<feature>/fix.md`.
`tests/test_fix_feature.py`	New tests validating the command/template structure and packaging inclusion.
`pyproject.toml`	Includes `templates/fix-template.md` in the wheel force-include bundle.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/commands/fix.md

tests/test_fix_feature.py

templates/fix-template.md

mnriem

Please deliver this as an extension. See https://github.com/github/spec-kit/tree/main/extensions for the information on how to develop an extension. And see any of the listed community extensions as examples at https://github.com/github/spec-kit?tab=readme-ov-file#-community-extensions

…ndatory validation step, trim redundancy

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/fix-template.md

templates/commands/fix.md

…tests (89 total)

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-31T23:44:47Z

templates/commands/ask.md

+---
+description: Answer any question about the current feature, project, or Spec Kit workflow — grounded in the constitution, existing specs, and best practices — and route to the right next command.
+handoffs:
+  - label: Fix an Error
+    agent: speckit.fix
+    prompt: "Fix this error: "
+  - label: Write a Spec
+    agent: speckit.specify
+    prompt: "Specify the following feature: "
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json --paths-only
+  ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty). This may be any question: conceptual, technical, workflow-related, or about a specific feature.
+
+---
+
+## Goal


This PR adds a new /speckit.ask command template (templates/commands/ask.md), but the PR title/description only mention /speckit.fix and the fix-log template. Please update the PR description to include /speckit.ask (or split it into a separate PR) so reviewers/users aren’t surprised by the extra command being shipped.

omgbwa-yasse requested a review from mnriem as a code owner March 31, 2026 16:07

Copilot AI review requested due to automatic review settings March 31, 2026 16:07

Copilot started reviewing on behalf of omgbwa-yasse March 31, 2026 16:07 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

templates/commands/fix.md Outdated Show resolved Hide resolved

templates/commands/fix.md Show resolved Hide resolved

templates/commands/fix.md Show resolved Hide resolved

tests/test_fix_feature.py Show resolved Hide resolved

templates/fix-template.md Show resolved Hide resolved

mnriem requested changes Mar 31, 2026

View reviewed changes

omgbwa-yasse added 2 commits March 31, 2026 18:10

feat(fix): add Phase 0 pre-flight, scope guard, third-party guard, ma…

342b74e

…ndatory validation step, trim redundancy

feat: add /speckit.ask command — grounded Q&A with workflow routing

e3b4fc6

Copilot AI review requested due to automatic review settings March 31, 2026 22:19

Copilot started reviewing on behalf of omgbwa-yasse March 31, 2026 22:20 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

templates/fix-template.md Show resolved Hide resolved

templates/commands/fix.md Show resolved Hide resolved

templates/commands/fix.md Show resolved Hide resolved

templates/commands/fix.md Show resolved Hide resolved

omgbwa-yasse added 2 commits March 31, 2026 18:23

fix(ask): wire speckit.ask into ecosystem — command map, routing, 30 …

3fb7d36

…tests (89 total)

fix(ask): make Phase 3 routing conditional, add direct question category

cf21fe5

Copilot AI review requested due to automatic review settings March 31, 2026 23:40

Copilot started reviewing on behalf of omgbwa-yasse March 31, 2026 23:40 View session

fix(ask): resolve 5 structural anomalies in ask.md

21bd0ec

Copilot AI reviewed Mar 31, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add `/speckit.fix` command and fix-log template#2033

feat: add `/speckit.fix` command and fix-log template#2033
omgbwa-yasse wants to merge 6 commits intogithub:mainfrom
omgbwa-yasse:main

omgbwa-yasse commented Mar 31, 2026

Uh oh!

mnriem commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

omgbwa-yasse commented Mar 31, 2026

Summary

What was added

templates/commands/fix.md — New /speckit.fix command

templates/fix-template.md — Fix-log template

tests/test_fix_feature.py — 39 tests (all passing)

pyproject.toml — updated

Design principles followed

Testing

Uh oh!

mnriem commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`templates/commands/fix.md` — New `/speckit.fix` command

`templates/fix-template.md` — Fix-log template

`tests/test_fix_feature.py` — 39 tests (all passing)

`pyproject.toml` — updated

mnriem left a comment •

edited

Loading