spec-update

Spec Update

Update an existing HTML specification document based on a user instruction, maintaining bidirectional link integrity throughout.

When to Use

Auto-trigger when:

• User says "change the spec to...", "update the spec...", "the spec should say..."
• User describes a change to existing behavior or requirements
• User corrects or refines something already in the spec
• spec/index.html exists and the user is not starting a brand-new idea

Hard Gate

DO NOT write any files until the user has approved the proposed changes. Always state exactly what will change before changing it. Surprise edits to specs are high-cost mistakes.

Step 1: Understand the Change

If the change instruction is ambiguous, ask one targeted clarifying question. Otherwise proceed immediately. If the change is still ambiguous after one clarifying question, ask the user to restate the instruction before proceeding.

Step 2: Find Affected Parts

Identify:

• Which files are affected (spec/index.html, spec/glossary.html, spec/auth.html, etc.)
• Which sections within those files change
• Which glossary terms are added, removed, or redefined
• Which bidirectional links need updating as a result

Step 3: Propose Changes

Tell the user exactly what will change before touching any file. Example:

"I'll make these changes:

• spec/index.html #what: add a paragraph describing the new export behavior
• spec/glossary.html: add term export-job with a reference back to #what

Go ahead?"

If a term is being removed, count its usages across all spec files and report before approval: "This term is used N times across X files. I'll remove all references."

Wait for explicit approval before writing.

Step 4: Update Files

Make the approved changes. Editing rules:

• Maintain 2-space indentation throughout
• Preserve all existing bidirectional links that were not part of the change
• If a section was renamed: update every <footer> reference in glossary.html that pointed to it
• If a section moves to a new file (e.g., index.html → auth.html):
  • Create the new file following the same HTML structure as index.html
  • Update all <footer> references in glossary.html to point to the new file
  • Remove the section from the original file
  • Add a link from index.html to the new file
• If a new term was added: wrap its first occurrence in spec body with <a href="glossary.html#term-NAME" class="term">TERM</a>
• If a term was removed from glossary: remove all class="term" links to it in spec files

Step 5: Verify Link Integrity

After editing, verify:

1. Every class="term" link in spec files points to an existing id="term-..." in glossary.html
2. Every <footer> reference in glossary.html points to an existing id="..." in a spec file
3. No orphaned anchors remain (An orphaned anchor is an id='...' that is not referenced by any link within the spec/ directory)
4. Ensure all edited HTML is well-formed: no unclosed tags, valid attribute syntax
5. If a new term was added, verify its first occurrence in spec files has a class='term' wrapper

If a broken link is found, fix it before committing.

Step 6: Commit

git add <each file you changed, listed explicitly>
git commit -m "spec: [short description of what changed and why]"

Stage only the files you actually changed. Do not use git add spec/ or git add . — those can accidentally stage unrelated files.

The commit message should capture why the spec changed (the intent), not just what lines moved.

Good: spec: narrow out-of-scope to exclude batch imports (v1 only) Bad: spec: update index.html