[Bug]: /speckit-analyze freezes in long sessions after context:fork added in #2511

[LeandroDeMeloGomesDev]

Summary

`/speckit-analyze` freezes or becomes very slow when run in a long session since `context: fork` was added in #2511 (shipped in v0.11.8). The change is well-intentioned but rests on an assumption that breaks in practice.

Environment

• Spec Kit version: 0.11.8 (Claude integration installed 2026-06-26)
• Agent: Claude Code

Steps to Reproduce

1. Start a Claude Code session and do any meaningful work (10+ messages)
2. Run `/speckit-analyze` — note: output is 300–500 lines of markdown with 6+ tables
3. Continue the session (discuss findings, run other commands, etc.)
4. Run `/speckit-analyze` again in the same session
5. Observe: the second and subsequent runs are noticeably slower, eventually freezing the chat output

The freeze does not occur in a fresh session (first message = `/speckit-analyze`).

Root Cause

PR #2511 added `context: fork` + `agent: general-purpose` to the generated `speckit-analyze` SKILL.md via `FORK_CONTEXT_COMMANDS` in `src/specify_cli/integrations/claude/init.py`.

The PR description states:

No conversation history needed. The task is fully described by the skill content and `$ARGUMENTS`.
Heavy inputs that collapse to a short report.

Both assumptions fail in practice:

1. The report is not short. A realistic spec (9 FRs, 8 SCs, 24 tasks, constitution) produces 300–500 lines of markdown — not a "compact findings table". This output is injected back into the main conversation on every run.

2. Each subsequent fork in the same session inherits a larger context. Because the previous analyze output (400 lines) lands in the main conversation, the next fork starts with an even bigger context to copy. The overhead compounds with each run.

Before #2511, `/analyze` ran directly in the main agent (which already had the context loaded). Spawning a fresh subagent, copying the full conversation, loading all spec artefacts, generating a 400-line report, and returning it to the main conversation adds significant overhead — especially on repeated runs.

Suggested Fix

Option A (minimal): Remove `analyze` from `FORK_CONTEXT_COMMANDS` — restore pre-#2511 behavior while the output format remains verbose.

Option B (intent-preserving): Keep `context: fork` but add a `## Summary` section at the top of the analyze output (5–10 lines max) and move the full findings table behind a `

Details

` block. The fork then genuinely returns a compact result to the main conversation, matching the PR's original intent.

Option B is better long-term but requires changes to `templates/commands/analyze.md`. Option A is a one-line rollback.

Impact

• Affects any user who runs `/speckit-analyze` more than once per session
• Likely under-reported because v0.11.8 shipped 2026-06-24 (2 days ago) and the issue only compounds on repeated runs in the same session

[github-actions]

Bug assessment — analyze-fork-context-bloat: Valid · severity high

---

Bug Assessment: /speckit-analyze freezes after repeated runs (context:fork bloat)

• Slug: analyze-fork-context-bloat
• Created: 2026-06-26T12:51:00Z
• Source: issue [Bug]: /speckit-analyze freezes in long sessions after context:fork added in #2511 #3185
• Verdict: valid
• Severity: high

Report (summarized)

Reported by @LeandroDeMeloGomesDev. Since v0.11.8 (shipped 2026-06-24), running /speckit-analyze more than once in the same Claude Code session causes progressive slowdowns and eventual output freezes. A fresh session is unaffected; the degradation compounds with each subsequent invocation.

The reporter correctly identifies PR #2511 (commit 98ee02a) as the root cause — it added context: fork + agent: general-purpose to the speckit-analyze skill. The report also proposes two concrete remediation options (remove from FORK_CONTEXT_COMMANDS or add a compact summary at the top of the output).

Symptom

When /speckit-analyze is run more than once in the same Claude Code session, each successive invocation is noticeably slower and eventually freezes chat output. The issue does not occur on the first run in a fresh session. Expected behavior: repeated invocations should have roughly uniform performance.

Reproduction

1. Start a Claude Code session and do meaningful work (≥10 messages).
2. Run /speckit-analyze — observe a 300–500 line markdown report with multiple tables.
3. Continue the session (discuss findings, run other commands).
4. Run /speckit-analyze again in the same session.
5. Observe: second run is noticeably slower; subsequent runs are slower still, eventually freezing.

Suspected Code Paths

• src/specify_cli/integrations/claude/__init__.py:29–31 — FORK_CONTEXT_COMMANDS dict adds "analyze": {"context": "fork", "agent": "general-purpose"}; this is the direct source of the injected frontmatter keys.
• src/specify_cli/integrations/claude/__init__.py:197–200 — post_process_skill_content() reads FORK_CONTEXT_COMMANDS and calls _inject_frontmatter_flag() for each key, writing context: fork and agent: general-purpose into the generated speckit-analyze/SKILL.md.
• templates/commands/analyze.md:162–190 — The "Produce Compact Analysis Report" section specifies up to 50 rows in the findings table, a coverage summary table, constitution alignment issues, unmapped tasks, and metrics — six or more tables in practice. This directly contradicts the "short summary" assumption that justified context: fork.
• tests/integrations/test_integration_claude.py:542–632 — Tests assert context: fork and agent: general-purpose are present in the analyze skill; these tests must be updated if analyze is removed from FORK_CONTEXT_COMMANDS.

Root Cause Hypothesis

Confidence: high.

PR #2511 justified context: fork on two assumptions that do not hold in practice:

1. "produces a compact analysis report" — The analyze template explicitly generates a structured multi-table markdown report (findings table capped at 50 rows, coverage summary, constitution issues, unmapped tasks, metrics). For a realistic spec (9 FRs, 8 SCs, 24 tasks, a constitution), this consistently produces 300–500 lines of output — not a compact summary.

2. "no need for conversation history" — With context: fork, the subagent starts with a copy of the main conversation at invocation time. After the first run lands ~400 lines of analyze output in the main conversation, the second fork inherits that enlarged context. Each run adds more output to the main context, which the next fork must copy. The overhead compounds quadratically: the nth fork carries (n-1) × ~400 lines of prior analyze output in its starting context, plus whatever else the user discussed in between.

The result is exactly the progressive slowdown described: run 1 is acceptable, run 2 is noticeably slower, run 3 or 4 freezes as the forked subagent tries to copy and process an ever-growing context window before it can even begin reading the spec artifacts.

Proposed Remediation

Preferred (Option A — immediate rollback):
Remove "analyze" from FORK_CONTEXT_COMMANDS in src/specify_cli/integrations/claude/__init__.py. This is a one-line change that restores pre-#2511 behavior. The original issue #752 (context pollution from heavy artifact reads) is a real concern, but it is less harmful than progressive session freezes. Shipping a regression-fix in a patch release is the right call while the longer-term intent-preserving option is designed.

Alternatives:

• Option B (intent-preserving): Keep context: fork but overhaul the analyze output so the result injected into the main conversation is genuinely compact (e.g., a 5–10 line summary with high-level counts and critical issues), while the full findings table is written to a file or suppressed from the returned output. This requires coordinated changes to templates/commands/analyze.md — specifically the "Produce Compact Analysis Report" section — and acceptance criteria for "compact" must be defined before implementing. This is a v0.12 candidate, not a hotfix.

• Option C (partial): Keep context: fork but document the session-reuse behavior as a known limitation and recommend users open a fresh session before re-running analyze. This is the weakest option and only appropriate as a temporary workaround note in the release announcement, not as a fix.

Files likely to change (Option A):

• src/specify_cli/integrations/claude/__init__.py — remove "analyze" entry from FORK_CONTEXT_COMMANDS (line 30)
• tests/integrations/test_integration_claude.py — update TestClaudeForkContext class: test_analyze_skill_runs_in_forked_subagent, test_fork_flags_inside_frontmatter, test_fork_injection_idempotent, test_fork_context_injected_via_post_process, and test_post_process_fork_idempotent all assert context: fork and agent: general-purpose on the analyze skill; these must be removed or inverted

Tests to add or update (Option A):

• Add a new test asserting that the speckit-analyze SKILL.md does not contain context: fork or agent: general-purpose after setup.
• Add a regression test confirming FORK_CONTEXT_COMMANDS is empty (or does not include analyze) to prevent re-introduction.

Risks & Considerations

• Regression risk: Option A reverts the intent of feat(claude): run /analyze in a forked subagent #2511 which addressed issue Feature Request: Utilize Claude Code's Subagent Feature for Command Execution #752 (heavy artifact reads bloating main conversation context). That concern is real but is outweighed by the current regression.
• Test churn: Several tests in TestClaudeForkContext exist specifically to assert the presence of context: fork on analyze; removing it means those tests must change. Care should be taken to replace them with tests that lock in the absence of the flag rather than simply deleting the test coverage.
• Version: v0.11.8 shipped 2026-06-24; this is a two-day-old regression. A patch release (v0.11.9) is appropriate for Option A.
• Under-reporting: As the reporter notes, the issue compounds only on repeated runs — users who only run analyze once per session will not observe the problem. Real-world exposure will grow as more users upgrade to v0.11.8.
• No data loss or security risk: This is a performance/UX regression only; no data is corrupted or leaked.

Open Questions

• [NEEDS CLARIFICATION: What is the observed behavior of context: fork in Claude Code when the subagent returns a large output — does the entire output land in the main context, or is it summarized? The answer affects whether Option B is viable without agent-side changes.]
• [NEEDS CLARIFICATION: Was issue Feature Request: Utilize Claude Code's Subagent Feature for Command Execution #752 fully addressed by feat(claude): run /analyze in a forked subagent #2511, or is there a separate tracking issue for the broader context-pollution concern that Option A would leave open?]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous).

Generated by 🐛 Assess Bug from Labeled Issue for issue #3185 · 139.5 AIC · ⌖ 25.2 AIC · ⊞ 31.7K · ◷