Repository navigation
fix(bug): document installed command names and stale re-assessment flow - #5069
Open
ShahabAhmed01 wants to merge 3 commits into
Open
ShahabAhmed01 wants to merge 3 commits into
ShahabAhmed01 wants to merge 3 commits into
Conversation
|
|
||
| - Ensure the directory `.specify/bugs/<BUG_SLUG>/` (i.e., `BUG_DIR`) exists, creating it (including any missing parents) if necessary. Use whatever mechanism is appropriate for the current environment. | ||
| - If `BUG_DIR/assessment.md` already exists, ask the user whether to overwrite it before continuing (in interactive mode); in automated mode, refuse and pick a new unique slug instead. | ||
| - If an overwrite is confirmed (interactive mode) and `BUG_DIR` also contains `fix.md` or `test.md` from an earlier run of this workflow, those reports describe the superseded assessment. After writing the new `assessment.md`, ask the user what to do with them: |
Comment on lines
+38
to
+40
| - **Staleness check** — a `fix.md` older than the current `assessment.md` describes a superseded bug (it can happen when the bug is re-assessed after the fix was applied, leaving the old fix and test reports in place). Compare the **Created** date in `assessment.md` with the **Fixed** date in `fix.md`, falling back to the files' modification times if a header date is missing: | ||
| - If the assessment was written after the fix, stop. Do not validate; tell the user to first re-run `__SPECKIT_COMMAND_BUG_FIX__ slug=<BUG_SLUG>` against the current assessment, then re-run this command. | ||
| - If the dates cannot be compared in this environment, ask the user to confirm that `fix.md` still corresponds to the current `assessment.md` (interactive mode) or refuse with the same instruction (automated mode). |
| text = (EXT_DIR / "commands" / "speckit.bug.assess.md").read_text( | ||
| encoding="utf-8" | ||
| ) | ||
| assert "stale" in text |
Comment on lines
+32
to
+40
| The dotted `speckit.bug.*` names above are the extension's canonical command IDs — what `extension.yml` declares, what `specify extension list` shows, and what hook configuration references. When the commands are registered with an AI agent they are installed as hyphenated skill names, and the spelling you invoke depends on the agent: | ||
|
|
||
| | Where | Invocations | | ||
| |-------|-------------| | ||
| | Claude Code, GitHub Copilot, Cursor, Devin and the other slash agents | `/speckit-bug-assess`, `/speckit-bug-fix`, `/speckit-bug-test` | | ||
| | Codex, ZCode, Command Code (skills mode) | `$speckit-bug-assess`, `$speckit-bug-fix`, `$speckit-bug-test` | | ||
| | Kimi | `/skill:speckit-bug-assess`, `/skill:speckit-bug-fix`, `/skill:speckit-bug-test` | | ||
|
|
||
| See [Command invocation](../../docs/integrations/cli.md#command-invocation) for the shared table, and the examples below use the slash-agent spelling. |
Collaborator
|
First thanks for clarifying the invocation guidance. Please align the bug README with the main README: use GitHub Copilot’s default skills syntax throughout, including the command table, examples, and handoff references, rather than retaining dotted command IDs or listing other agents’ syntax variations. Use the same wording as the main README:
This keeps the README focused on one consistent syntax and leaves integration-specific variations in the shared reference. Please retain the clarification that skills run in the agent’s chat, not the terminal. For the rest please address the Copilot feedback above. If not applicable, please explain why |
The bug extension's README documented only the dotted canonical command IDs (e.g. /speckit.bug.assess), which are the extension.yml command IDs, not the names agents install. Skills-based integrations collapse dots to hyphens (speckit-bug-assess) and the invocation prefix varies by agent: / for Claude Code, Copilot and the other slash agents, $ for Codex/ZCode/Command Code, /skill: for Kimi (matched by docs/integrations/cli.md#command-invocation and the integration guides). The README now documents the installed names and uses the working invocations in the typical-flow examples. Re-assessing a bug that already had fix.md / test.md left the older reports in place while validation read them together with the rewritten assessment. After a confirmed assessment overwrite, assessment now asks what to do with sibling fix.md / test.md - offering to rename them to *.stale.md (never delete) or flagging them as stale in the Completion Report; automated mode is unchanged (it already refuses the overwrite). Validation (speckit.bug.test) now refuses a fix.md older than the current assessment.md, comparing the reports' header dates with a file- mtime fallback, and asks to confirm (interactive) or refuses (automated) when timestamps cannot be compared. Static regression tests assert the exact previously-absent strings, so they fail on main and pass with this change. Assisted-by: OpenCode (model: GLM-5.3-Flash Free, autonomous)
ShahabAhmed01
force-pushed
the
contrib/issue-5036-bug-extension-stale-reports-0f9d84c3
branch
from
October 23, 2026 16:43
45e3404 to
a830290
Compare
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved release-metadata and stale-report validation defects block approval.
7 open issues
Review effort: Max
| id: bug | ||
| name: "Bug Triage Workflow" | ||
| version: "1.0.1" | ||
| version: "1.0.2" |
Comment on lines
+32
to
+40
| The dotted `speckit.bug.*` names above are the extension's canonical command IDs — what `extension.yml` declares, what `specify extension list` shows, and what hook configuration references. When the commands are registered with an AI agent they are installed as hyphenated skill names, and the spelling you invoke depends on the agent: | ||
|
|
||
| | Where | Invocations | | ||
| |-------|-------------| | ||
| | Claude Code, GitHub Copilot, Cursor, Devin and the other slash agents | `/speckit-bug-assess`, `/speckit-bug-fix`, `/speckit-bug-test` | | ||
| | Codex, ZCode, Command Code (skills mode) | `$speckit-bug-assess`, `$speckit-bug-fix`, `$speckit-bug-test` | | ||
| | Kimi | `/skill:speckit-bug-assess`, `/skill:speckit-bug-fix`, `/skill:speckit-bug-test` | | ||
|
|
||
| See [Command invocation](../../docs/integrations/cli.md#command-invocation) for the shared table, and the examples below use the slash-agent spelling. |
Comment on lines
+38
to
+40
| - **Staleness check** — a `fix.md` older than the current `assessment.md` describes a superseded bug (it can happen when the bug is re-assessed after the fix was applied, leaving the old fix and test reports in place). Compare the **Created** date in `assessment.md` with the **Fixed** date in `fix.md`, falling back to the files' modification times if a header date is missing: | ||
| - If the assessment was written after the fix, stop. Do not validate; tell the user to first re-run `__SPECKIT_COMMAND_BUG_FIX__ slug=<BUG_SLUG>` against the current assessment, then re-run this command. | ||
| - If the dates cannot be compared in this environment, ask the user to confirm that `fix.md` still corresponds to the current `assessment.md` (interactive mode) or refuse with the same instruction (automated mode). |
Collaborator
|
Please simplify this further. If the selected bug directory already contains an assessment, fix, or test report, the assessment command should inform the user and stop without changing anything. A fresh assessment should use a new slug. This removes the stale-report problem at its source. Please remove the assessment-overwrite path and the proposed archive/rename and timestamp-checking logic; the fix and test commands do not need additional freshness handling for this scenario. Keep the README correction aligned with the guidance already provided, and demonstrate that assessment stops without modifying existing reports, while assessment under a fresh slug still works. AI disclosure: Drafted and posted for @mnriem by GitHub Copilot, powered by GPT-6.1 Sol, in an interactive, user-directed session; assessment and response wording are AI-generated. |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Fixes #5036.
Two gaps in the bundled
bugextension's README and command templates:1. Documented invocations don't match installed command names.
extensions/bug/README.mdshowed only the dotted canonical IDs (e.g./speckit.bug.assess), which are theextension.ymlcommand IDs, not the names agents install. Skills-based integrations collapse dots to hyphens (speckit-bug-assess) and the invocation prefix varies by agent:/for Claude Code, Copilot and the other slash agents,$for Codex/ZCode/Command Code,/skill:for Kimi — the same mappingdocs/integrations/cli.md#command-invocationdocuments and the integration guides and root README already use. The README now has an "Installed command names" table (plus a stale-report guardrail row in Guardrails), and the typical-flow examples use the working/speckit-bug-*spellings.2. Re-assessing a bug leaves the old
fix.md/test.mdin place, and validation treats them as current.speckit.bug.assess.md: after a confirmed assessment overwrite (interactive mode), the command now asks what to do with siblingfix.md/test.mdfrom the earlier triage — offering to rename them tofix.stale.md/test.stale.md(never delete; disambiguating suffix if a.stale.mdname is taken), or leaving them in place but calling them out as stale in the Completion Report. Automated mode is unchanged: it already refuses the overwrite and picks a new unique slug, so sibling reports are never disturbed.speckit.bug.test.md: a new Staleness check prerequisite stops validation whenassessment.mdwas written afterfix.md— comparing the reports' header dates (CreatedvsFixed), falling back to the files' modification times — and instructs the user to re-run the fix step against the current assessment first. If timestamps cannot be compared in the environment, the user confirms the correspondence (interactive mode) or the command refuses (automated mode). Also mirrored in the template's Guardrails.These are prompt-template/README changes only; no Python runtime code and no
.lock.ymlregeneration is involved (the lock files import the markdown at runtime).Testing
Tested locally with
uv run specify --help(CLI entry points unaffected; template-only change)Ran existing tests with
uv sync && uv run pytestTested with a sample project (if applicable)
Full suite on the final tree (Python 3.14.8,
uv run pytest tests -q): 12,735 passed, 461 skipped, 0 failed — 12,728 before the change plus the 7 new template-text tests;git diff --checkclean.New regression tests in
tests/extensions/bug/test_bug_extension.py(TestStaleReportGuardrails, plusTestExtensionLayoutREADME-name checks) assert the exact strings that are absent onmainand present after this change. Red/green proven in a separate worktree: againstorigin/main@27d14e2with the same test file, the 7 new tests fail (7 failed, 27 passed); with this change all 34 extension tests pass. Since the change is template content itself, the text tests pin the documented behavior; if maintainers want runner-level proof instead/also, I can extend on request.AI Disclosure
AI disclosure: Acted via OpenCode agent (model: GLM-5.3-Flash Free, autonomous) on behalf of ShahabAhmed01. Autonomous run (run id
ossrun-20261023T123818Z-0f9d84c3): researched the issue queue with no competing PR, selected #5036 after verifying it was bot-validated (triage-must-have,severity-medium) with no human claim, read the extension README, the three command templates,docs/integrations/cli.md#command-invocationand the skill-name/invocation-style code (src/specify_cli/_invocation_style.py, integrations' hyphenated-name computation), then authored the README/assess/test template additions and the seven regression tests in this PR (documentation and prompt-template content plus their tests; no Python runtime code). Verified remotely before opening; the commit carries an equivalentAssisted-by:trailer.