# 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 | !!! tip "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: ```powershell git checkout -b docgen/fix- ``` ## 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 CLI" Select the **SAIF Doc Gen** agent, then send the report as a message. The command token works anywhere in the sentence. ```text 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. ``` ```text Do a /docgen-quickfix ref: docs/libraries/saif-framework-core/architecture.md issue: The architecture diagram renders as raw text instead of a diagram. ``` === "VS Code / Visual Studio" 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. ```text /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. ``` !!! warning "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--/`, 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](#scoped-re-run) | | The tooling itself is out of date | [Refresh the tooling](#refresh-the-tooling) | | Source changed substantially across many libraries | Full re-run — see [Quick start](quick-start.md) | ### 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. ```text 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: ```powershell 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: ```powershell 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: ```powershell legends init --clear-state ``` !!! note "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](reviewing-documentation.md), then open a pull request against the repository's default branch. Once merged, refresh the portal copy as described in [Publishing to the portal](publishing-to-portal.md).