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.md exists (for example, written by a
before_bug_assess hook), 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 to evidence.md, and the assessment cites the first error and the
crash-loop pattern from it.
speckit.bug.test fails and recommends re-running assess. The new failing
log goes through the same intake, so evidence.md shows the before and
after.
Acceptance Criteria
I'm happy to send the PR.
Additional Context
AI Disclosure
Drafted with Claude Code (Claude Opus 5.5) from my notes. I reviewed it.
Problem Statement
speckit.bug.assessingests a bug report as pasted text or a URL. Real bugreports often come with a log: a CI run,
kubectl logs, a crash-loopingservice. 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>/, sospeckit.bug.fixandspeckit.bug.testcan'trely 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:Also add
evidence.md(optional) to the per-bug directory layout in theREADME, alongside
assessment.md,fix.mdandtest.md.This names no tool. With no
evidence.md, behavior is exactly as today. Thefile can be written by hand or by any extension. Using the
before_bug_assesshook from #4799 is the natural route, but this conventionworks without that hook.
Motivating producer: log intake
A community extension,
speckit.logreduce.intake,finds log files referenced in the report and runs
logreducewith a token budget.logreduceis a single static binary that applies TF-IDF over masked templatesplus severity weighting. The extension writes
BUG_DIR/evidence.mdcontainingthe command it ran, the source path, the summary header and the reduced log.
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
speckit.bug.assess. That adds a tool-specificdependency to a bundled extension. A file convention keeps core neutral.
today, but assess doesn't know to read the result.
Component
Extensions: bundled
bugextension (extensions/bug/)AI Agent (if applicable)
All.
Use Cases
log to
evidence.md, and the assessment cites the first error and thecrash-loop pattern from it.
speckit.bug.testfails and recommends re-running assess. The new failinglog goes through the same intake, so
evidence.mdshows the before andafter.
Acceptance Criteria
speckit.bug.assessreadsBUG_DIR/evidence.mdwhen present and cites itunder Report.
evidence.md(optional) is listed in the per-bug directory layout in thebug extension README.
evidence.md, the command output is unchanged.I'm happy to send the PR.
Additional Context
bugextension commands #4799 (hook events for the bug commands) at a maintainer's request.spec-kit-bugfixextension (speckit.bugfix.report) could readevidence.mdin the same way.AI Disclosure
Drafted with Claude Code (Claude Opus 5.5) from my notes. I reviewed it.