docs(templates): clarify /constitution's Sync Impact Report is temporary, review-only material (#4431) - #4432
Open
chelsealong wants to merge 2 commits into
Conversation
…ithub#4431) Step 4 of the constitution command only said to prepend the Sync Impact Report as an HTML comment, with no instruction to remove a previous one. Each run therefore added another report block on top of the last, growing the raw file (and the token cost of reading it) without bound. Now the step explicitly requires removing any existing report comment before adding the new one. Assisted-by: Claude (model: claude-sonnet-5, autonomous)
mnriem
requested changes
Sep 3, 2026
mnriem
left a comment
mnriem
left a comment
Collaborator
There was a problem hiding this comment.
As indicated by the comment on the issue please change this to a documentation issue
Per review on github#4432/github#4431: the growth this fixed isn't a functional bug in the intended workflow — the report is scratch material for human review and is expected to be removed before the constitution file is committed. Step 4 now says so explicitly, alongside the existing replace-not-stack instruction for runs where a prior report was left in place.
chelsealong
changed the title
Contributor
Author
|
Agreed, retitled as a docs clarification. Pushed 609dc58: Step 4 now states explicitly that the Sync Impact Report is temporary, review-only material expected to be removed before the constitution file is committed, alongside the existing replace-not-stack instruction for runs where a report was left in place ( |
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
2 participants
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.
Fixes #4431
Problem
templates/commands/constitution.md(Step 4 of the Outline section) instructedagents to "prepend" the Sync Impact Report as an HTML comment at the top of
.specify/memory/constitution.md, with no instruction to remove a previousreport first. Because HTML comments are invisible in rendered Markdown but
fully present in the raw file, every
/constitutionrun stacked another<!-- ... -->report block on top of the last one. Any agent or extensionhook that loads the raw constitution file at runtime (
/specify,/review,before_constitution/after_constitutionhooks, etc.) pays a growing,unbounded token cost reading historical changelog data that has no
governance value at inference time.
Fix
Step 4 now explicitly instructs the agent to remove any existing HTML
comment at the top of the file before adding the new Sync Impact Report,
so the file never carries more than one report — it is replaced, not
stacked.
This is a one-line-of-behavior instruction change to the command template
(
templates/commands/constitution.md); no other copies of this text existin the repo.
Test plan
Added
tests/test_constitution_template_sync_report.py, which asserts theStep 4 instructions require removing any prior Sync Impact Report comment
rather than only prepending.
(
git checkout HEAD~1 -- templates/commands/constitution.md):uv run --extra test pytest -qAI disclosure
This change, including the code, tests, and this PR description, was
generated autonomously by an AI coding agent (Claude, model: claude-sonnet-5)
acting on behalf of the repository owner, with no line-by-line human review
prior to commit.
Assisted-by: Claude (model: claude-sonnet-5, autonomous)