Bugfix / quick fix

A full doc gen run is expensive, and most problems found during review do not need one. The toolkit ships two commands for repairing documentation that already exists:

	/docgen-bugfix	/docgen-quickfix
Use for	Any real defect — wrong, missing, or misleading content	A presentation-only problem you have already judged small
Examples	An incorrect business rule, a missing page, a claim with no source, the same wrong fact repeated across documents	A Mermaid diagram that will not render, a broken markdown table, a typo
What it does	Opens a tracked run: triage, tier assignment, sub-agent dispatch, review and remediation, closeout report	The orchestrator fixes it directly — no run folder, no sub-agents
Scope	Sized from evidence; looks for the same defect elsewhere	Exactly what you reported, and nothing else

When in doubt, use /docgen-bugfix

An unnecessary tracked run costs one extra sub-agent. A quickfix applied to a defect that was not actually cosmetic puts an unreviewed edit into a published document.

Both commands run against the repository containing the documentation, with the SAIF Doc Gen agent selected. Work on a branch, the same as a full run:

git checkout -b docgen/fix-<what>

How to invoke them

Slash commands are not natively supported everywhere. The GitHub Copilot app and Copilot CLI do not execute prompt files, so the orchestrator detects the command token in your message and runs the prompt file itself.

That means you type the command as part of a normal sentence, and you supply the ref: and issue: lines yourself — there is no argument parser filling them in.

GitHub Copilot App / Copilot CLIVS Code / Visual Studio

Select the SAIF Doc Gen agent, then send the report as a message. The command token works anywhere in the sentence.

Do a /docgen-bugfix
ref: docs/libraries/saif-framework-security/business-rules.md
issue: BR-004 says the token expires after 30 minutes, but the code uses a
60 minute sliding expiration.

Do a /docgen-quickfix
ref: docs/libraries/saif-framework-core/architecture.md
issue: The architecture diagram renders as raw text instead of a diagram.

Prompt files are executed natively, so /docgen-bugfix and /docgen-quickfix appear in the slash command list. Supply the same ref: and issue: detail as the argument.

/docgen-bugfix
ref: docs/libraries/saif-framework-security/business-rules.md
issue: BR-004 says the token expires after 30 minutes, but the code uses a
60 minute sliding expiration.

Always include ref: and issue:

ref: scopes the work. Without it the orchestrator has to guess which documents are affected, and a bugfix run will widen its search to find out. issue: is what gets triaged — "this page looks wrong" produces a slower and less accurate run than naming the specific defect.

If you send either command with no arguments, it stops and asks you for both before doing anything else.

/docgen-bugfix — tracked remediation

This is the default. It runs the reported issue through the same state machinery as a generation run, so the fix is triaged, tracked, reviewed, and reported.

What happens

1. Establish the run. A run folder is created at .saifdocgen/state/runs/bugfix-<timestamp>-<issue-slug>/, the context set is loaded and attested, and the generation run that produced the offending documents is identified as read-only evidence.
2. Triage. The defect is reproduced from the documents on disk, classified into a fix tier, and — for T2 and above — put to a short specialist advisory round. A ripple scan then finds every other document in the reported library carrying the same fact. Nothing under docs/ is touched until triage.md is written.
3. Plan. Every task is written upfront and sequenced, with disjoint fixes batched async and same-file fixes kept serial.
4. Dispatch. Sub-agents run the batches under the persona and model the tier assigns.
5. Review and remediate. The changed documents and their ripple set are reviewed, then remediated until the verdict passes or the remediation budget is exhausted.
6. Close out. A bugfix-report.md is written, and a systemic defect also gets a decision-log.md entry.

Gates are mechanical — Assert-BugfixGate.ps1 must return PASS at each step boundary, and the agent will not reason past a BLOCKED verdict.

Fix tiers

Triage assigns a tier, and the tier determines who does the work. It follows the evidence, not how big the edit looks.

Tier	Name	What it covers	Executor
T0	Cosmetic	Typo, formatting, heading shape, broken relative link, table alignment, Mermaid syntax. No semantic claim changes.	Orchestrator itself
T1	Local content	Wrong, missing, or unclear content confined to one document, recoverable from existing analysis findings.	Technical Writer
T2	Systemic — mechanical repetition	The same defect repeated across many documents, where the correction is mechanical.	Technical Writer (batched)
T3	Analytical	A claim about code, SQL, security, or configuration behavior that is wrong or unverifiable. Requires re-reading source.	Programmer Analyst → Technical Writer
T4	Structural / cross-document	The fix changes the shape or assertions of the documentation set — architecture narrative, business-rule identity, application rollups, restructured navigation, or a page the source run should have produced and did not.	Technical Architect → Technical Writer

Two behaviors are worth knowing as a reporter:

• You describe the symptom; the ripple scan decides the depth. The run is never sized from how you worded the report. It is also never widened past the library or application you named — a suspected broader problem is recorded as a follow-up rather than chased.
• When two tiers are defensible, the higher one wins, and the reason is recorded.

/docgen-quickfix — one small presentation fix

This is the T0 lane with the run machinery stripped away: no run folder, no task files, no gates, no sub-agents. It exists because a Mermaid diagram that will not render does not need a five-gate tracked run.

It is not a fast path for everything else. Eligibility is a closed list, checked against the file on disk rather than against how confident the fix feels. All six must hold:

1. Presentation only. The fix changes how existing content renders or reads, never what it asserts. Correcting Mermaid syntax qualifies; correcting an arrow's direction because the flow is wrong does not.
2. Self-contained. The correct output is determinable from the file itself and the writing-standards skill. If answering "what should this say?" needs source code, SQL, config, or a prior run's findings, it does not qualify.
3. Within the file threshold. At most bugfix.cosmeticFileThreshold files (default 2), and only the files you named.
4. No new files. Creating a page, section, or folder is at minimum T4.
5. Not generated-from-a-set. No edit to an index, manifest, mkdocs.yml, navigation, or any cross-document rollup — fixing one entry by hand desynchronizes the generator.
6. Not a business rule's identity, condition, or enforcement location — those propagate to operations, architecture, and application rollups.

If any rule fails, the command changes nothing on disk. It tells you which rule failed, what the defect actually appears to be, the tier it expects /docgen-bugfix would assign, and asks whether to hand the report over. It will not escalate on its own, and it will not apply a partial fix as a compromise.

What it will not do

/docgen-quickfix has no ripple scan and no license to improve anything it happens to notice. If you report one broken table, it fixes that table — it does not scan the file for others, check sibling documents, or fix a second one on the way past. Anything else it spots is listed in its final report and left on disk for you to send back as its own request.

Every invocation appends a row to .saifdocgen/state/quickfix-log.md, which is the only durable trace a quickfix leaves.

When neither command is the answer

Situation	Approach
One library, screen, or application is genuinely out of date because the source changed	Scoped re-run
The tooling itself is out of date	Refresh the tooling
Source changed substantially across many libraries	Full re-run — see Quick start

Scoped re-run

Doc gen works at per-library task granularity, so pointing it at a single target generates only that target's tasks. This is regeneration, not repair — use it when the source moved, not when the documentation is wrong about source that did not.

Regenerate documentation for the SAIF.Framework.Security library only. Do not
modify documentation for any other library. Run analysis, writing, review, and
index generation for that library, then update the root README and
docgen-manifest.md so their tables stay consistent.

Diff before you commit — a scoped run should touch only the files you asked about plus the index pages:

git status
git diff --stat

Refresh the tooling

Prompts, templates, and validation rules ship with the CLI, so an old checkout can be running rules that no longer match. Refresh before blaming the output:

legends update --install
legends init --dry-run    # review what would change
legends init

legends init is idempotent and hash-diffed, so it only rewrites files that actually differ. Run state under .saifdocgen/state/ is preserved unless you pass --clear-state, which is worth doing after an abandoned or crashed run:

legends init --clear-state

The toolkit is not a fix surface

Both commands may only write to docs/ and their own state folders. .saifdocgen/ and .github/ are delivered by the CLI and are overwritten on the next legends init, so a defect traced to a template or instruction is reported for the toolkit owners rather than patched locally.

Finishing up

A fix goes through the same gate as a full run: review the result, then open a pull request against the repository's default branch. Once merged, refresh the portal copy as described in Publishing to the portal.