[Feature]: `evidence.md` convention for `speckit.bug.assess` (pre-digested inputs such as reduced logs)
維護者通常 1 天內回覆
還沒有人認領這個 Issue。
評估
- 難度
- 2/5
- 預估耗時
- 1-3 小時
- 新手友好度
- 78/100
- Issue 類型
- 功能
- 描述清晰度
- 描述清楚
- 活躍度
- 活躍
- 領域
- documentation, tooling
研究方向
從 extensions/bug/ 開始，找到 speckit.bug.assess 的 Execution → 1. Ingest 說明，然後檢查隨附的 bug 擴充功能 README，了解每個 bug 的目錄配置。更新 ingest 行為並記錄可選的 evidence.md；當存在和缺少的檔案都符合驗收標準時即完成，包括在缺少 evidence.md 時輸出保持不變。
由索引模型根據 Issue 內容生成。
描述
Problem Statement
speckit.bug.assess ingests a bug report as pasted text or a URL. Real bug
reports often come with a log: a CI run, kubectl logs, a crash-looping
service. These run to thousands or millions of lines. Today the agent either
reads the raw log (blowing the context window and burying the one relevant
error under repeats) or skims it ad hoc. Whatever it looked at is not recorded
in .specify/bugs/<slug>/, so speckit.bug.fix and speckit.bug.test can't
rely on it, and a reviewer can't check what the agent actually saw.
Proposed Solution
In Execution → 1. Ingest the bug report of speckit.bug.assess, add:
If
BUG_DIR/evidence.mdexists (for example, written by a
before_bug_assesshook), read it as part of the report. Cite it under
Report and prefer it over re-reading any raw log it was derived from.
Also add evidence.md (optional) to the per-bug directory layout in the
README, alongside assessment.md, fix.md and test.md.
This names no tool. With no evidence.md, behavior is exactly as today. The
file can be written by hand or by any extension. Using the
before_bug_assess hook from #4799 is the natural route, but this convention
works without that hook.
Motivating producer: log intake
A community extension, speckit.logreduce.intake,
finds log files referenced in the report and runs
logreduce with a token budget.
logreduce is a single static binary that applies TF-IDF over masked templates
plus severity weighting. The extension writes BUG_DIR/evidence.md containing
the command it ran, the source path, the summary header and the reduced log.
- On a 1M-line log, that is a ~99.9% token reduction.
- On the LogDx CI-incident benchmark (35 cases), it kept 99% of the
human-labelled critical lines at an 8k-token budget.
Assess, fix and test then all work from the same saved evidence file instead of
the raw log. I'll maintain that extension and submit it to the community
catalog. This issue only asks for the convention.
Alternatives Considered
- Bake log reduction into
speckit.bug.assess. That adds a tool-specific
dependency to a bundled extension. A file convention keeps core neutral. - A standalone command the user runs first, with no convention. This works
today, but assess doesn't know to read the result.
Component
Extensions: bundled bug extension (extensions/bug/)
AI Agent (if applicable)
All.
Use Cases
- A CI job fails with a 40k-line log. Intake writes about 7k tokens of reduced
log toevidence.md, and the assessment cites the first error and the
crash-loop pattern from it. speckit.bug.testfails and recommends re-running assess. The new failing
log goes through the same intake, soevidence.mdshows the before and
after.
Acceptance Criteria
-
speckit.bug.assessreadsBUG_DIR/evidence.mdwhen present and cites it
under Report. -
evidence.md(optional) is listed in the per-bug directory layout in the
bug extension README. - With no
evidence.md, the command output is unchanged.
I'm happy to send the PR.
Additional Context
- Split from #4799 (hook events for the bug commands) at a maintainer's request.
- The community
spec-kit-bugfixextension (speckit.bugfix.report) could read
evidence.mdin the same way.
AI Disclosure
Drafted with Claude Code (Claude Opus 5.5) from my notes. I reviewed it.
- 主要語言
- Python
- 星號
- 139k
- 分支
- 12.5k
- 平均合併
- 2 天 19 小時
- 30 天內合併 PR
- 175
環境準備
在瀏覽器裡用你自己的 GitHub 帳號啟動這個專案的開發容器。
- 沒有 Dockerfile 或 Docker Compose 檔案
- 有 Pull Request 範本
- 閱讀貢獻指南
從這裡開始
- 先讀完整個 Issue，再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫，在一個分支上完成修改。
- 送出 Pull Request，並在描述裡引用這個 Issue 編號。
github/spec-kit 的其他 Issue
-
needs-triage triage-nice-to-have
難度 2/5 1-3 小時 新手友好度 72/100
github/spec-kit#4527 · 1 則留言 ·
維護者通常 1 天內回覆
-
bug-assess severity-medium
難度 2/5 1-3 小時 新手友好度 72/100
github/spec-kit#4273 · 3 則留言 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 84/100
維護者通常 1 天內回覆
-
extension-submission validation-passed
難度 2/5 1-3 小時 新手友好度 72/100
github/spec-kit#4099 · 3 則留言 ·
維護者通常 1 天內回覆
-
extension-submission validation-passed
難度 2/5 1-3 小時 新手友好度 66/100
github/spec-kit#3932 · 6 則留言 ·
維護者通常 1 天內回覆
相似的 Issue
-
難度 2/5 1-3 小時 新手友好度 85/100
維護者通常 1 天內回覆
-
approved correction metadata
難度 1/5 1 小時以內 新手友好度 88/100
acl-org/acl-anthology#10133 · 1 則留言 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 78/100
BasedHardware/omi#20084 ·
維護者通常 1 天內回覆
-
bug needs-acceptance wg/evaluation-quality
難度 2/5 1-3 小時 新手友好度 76/100
vllm-project/semantic-router#4424 ·
維護者通常 1 天內回覆
-
bug
難度 2/5 1-3 小時 新手友好度 68/100
openlibhums/janeway#5604 ·
維護者通常 1 天內回覆