[Bug] /dev-story's "Read ADR fully" instruction fails on ADRs >25k tokens, forcing offset/limit retries that double the read cost

[Shtruk]

Description

The Claude Code Read tool caps file content at 25,000 tokens per call.
/dev-story Phase 2 instructs Read("docs/architecture/[adr-file].md")
unconditionally. ADRs for non-trivial architectural decisions routinely
exceed this cap (35k+ tokens is common when the ADR includes detailed
Implementation Guidelines, Engine Compatibility tables, and Amendments).

The result is a failed Read, an error message instructing the agent to
retry with offset/limit, and 2-3 follow-up reads to assemble the
file in chunks. Total token cost: ~30k of input tokens spent on
failed-read errors + retry reads — roughly double what a successful
single Read would have consumed.

This compounds Issue #63: not only is the full ADR re-read redundant
per /create-stories' contract, it's also pathologically expensive on
realistic ADRs.

Steps to Reproduce

1. Create an ADR with substantial Implementation Guidelines + Amendments
   sections (target ~35k tokens / ~250 lines of dense prose)
2. Generate stories via /create-stories referencing that ADR
3. Run /dev-story on one of the stories
4. Observe the Read call on the ADR fails with:
   File content (35000+ tokens) exceeds maximum allowed tokens (25000). Use offset and limit parameters to read specific portions of the file...
5. Agent then issues offset+limit Reads to recover

Expected Behavior

Skills that need ADR content should use targeted reads (grep for
specific sections, or Read with offset/limit for known section
boundaries) rather than unbounded full-file reads.

Actual Behavior

Phase 2 instructions assume Read returns the full file; no
preconditioning for large ADRs.

Environment

• Template version: v1.0.0 (commit 984023d)

Affected Component

• Skill: dev-story
• Documentation: skill prescribes a read pattern that doesn't scale

Additional Context

Real-world example: a project with ADR-0007 (~35k tokens) and ADR-0009
(~35k tokens), both referenced by stories. Each /dev-story invocation
incurred ~60k of failed-read + retry overhead before implementation even
started. The Issue #63 fix (use story-embedded Decision Summary)
incidentally resolves this symptom; if Issue #63's fix is not adopted,
this issue should still be addressed with targeted Read patterns.

[elysi]

That's a Claude issue, not a CCGS issue, it's a library/template instruction set, you should look to develop tooling via your agent of choice to eliminate these. I have partial-reader-helper.sh, generate-adr-summaries.sh, anchor.json files that are read then contextually the skills know how to read the files deterministically.

Just explain your issue to Claude, read caps, large context etc, and ask it to build helper tools via summaries, partial read helpers, and anchor.json files, it will then write them into the code.

Ultimately, judging by your ADR size and token count, you're using CCGS for a large/complex project, where I believe the project is more aligned to smaller indie aspects, the project/template/context does work, but it requires iteration and retrospective input. You need to use a session with Claude/CCGS, explain the issues you're having and build tooling to aid.

I currently have 114 GDDs, and 21 ADRs, without the above tooling the project would be impractical. I've left a screenshot below to summarize simple steps I have taken

[Shtruk]

Thanks, that makes sense. I agree the 25k Read cap is mainly a Claude/tooling limitation, not something CCGS directly controls.

The linked issue #63 is more about the template contract: /create-stories embeds the ADR Decision Summary and Implementation Notes into the story, but /dev-story still tells the agent to re-read the full ADR and ignore inline story text. That makes the distillation step mostly redundant and very expensive on large ADRs.

The large-file read problem is a related symptom, not the main issue. Even with helper tooling, I think large ADRs/GDDs could also be structured in a more read-friendly way, for example as folders with INDEX.md, split sections, anchors, or summaries. But the core issue is that /dev-story should probably trust the story-embedded summary unless it is missing, stale, or ambiguous.

So I agree this is partly solved by tooling, and I have worked around it in my setup. I raised it because the default framework flow could be more opinionated here, especially for larger projects where ADRs/GDDs naturally become detailed.

[yujuiting]

@elysi I believe your solution is worth to be native of CCGS.

[elysi]

@elysi I believe your solution is worth to be native of CCGS.

I have now included generic versions of my helpers for everyone else to use, there is a README.md file that explains all the tools, you won't have to implement these, use the local/cloud based AI agent you're using to read the files, readme's, implementation files and get them put into your project. I can't export the entire solution as these are tried into skill/agent .MD files alongside other customisation.

This is now battle-tested across a multi-sprint CCGS deployment with ~100 GDDs, ~25 ADRs, 50+ stories, 8+ sprints as of now, I am only in about 10/15% of Sprints at the moment. I've gotten to the point with context/helpers that I can now author on Opus 4.7 (Max effort) 100% of the time without reaching weekly or session caps.

I do think the project template needs an iteration change to account for large projects. Ultimately it comes down to retrospective - I often see poor output, slow output, issues etc, and the first thing I do is retrospective with Opus to find the issues, build tooling to support better iteration.

Another explicit implementation in my project is I have an "Inline fix" memory, anything from code-review, or any other system that generates issues, if the fix is less than 10 lines, Opus is allowed to inline fix. Active.MD will grow out of control and so will Deferred Items and Tech Debt, this needs consistent management.

@Shtruk @yujuiting @Donchitos

ccgs-context-helpers-2026-05-30.tar.gz

[Huaian666]

switched our team over from the other thing last month. zero regrets. this just works without the constant fighting.

[ai-hustle-bro]

I made a small first-pass helper for the anchor/index pattern discussed above: https://gist.github.com/ai-hustle-bro/c487be5b3d91ec234ed723c2b7101463

It scans a large Markdown ADR/GDD and writes:

• INDEX.md with heading line ranges, rough token counts, and short previews
• anchors.json for deterministic targeted reads by an agent/skill

The intended rule is: read the generated index first, then read only the smallest relevant section range instead of asking the agent to read the full ADR. It doesn't modify the source doc or depend on CCGS internals, so it should be easy to adapt or discard.