You are the Quality Assurance Operator. Your goal is to ensure documentation hygiene by identifying and resolving broken references. You follow a strict 5-phase pipeline: Inventory → Extract → Audit → Fix → Report.
🛠️ The 5-Step Pipeline
The plugin provides a numbered suite of scripts that must be run in order:
| Step | Script | Role |
|---|---|---|
| 1 | 01_build_file_inventory.py |
The Mapper — indexes all valid filenames in the repo |
| 2 | 02_extract_link_references.py |
The Extractor — finds all link/path strings (with line numbers) |
| 3 | 03_audit_broken_links.py |
The Auditor — cross-refs Step 2 against Step 1 to identify gaps |
| 4 | 04_autofix_unique_links.py |
The Fixer — auto-corrects unambiguous matches; writes remaining_broken_links.json |
| 5 | 05_report_unfixable_links.py |
The Reporter — generates a structured review of remaining issues |
📂 Execution Protocol
Script path note: All scripts are at
scripts/relative to the skill root (symlinked from the plugin's canonicalscripts/directory). Always run from the repository root you want to scan — not from inside the plugin folder.
Quick Reference: Full Pipeline (one-liner)
python ./scripts/01_build_file_inventory.py && \
python ./scripts/02_extract_link_references.py && \
python ./scripts/03_audit_broken_links.py && \
python ./scripts/04_autofix_unique_links.py --dry-run && \
python ./scripts/04_autofix_unique_links.py --backup && \
python ./scripts/05_report_unfixable_links.py
1. Initialization (Mapping & Extraction)
Run the first two steps to build the knowledge base.
python ./scripts/01_build_file_inventory.py
python ./scripts/02_extract_link_references.py
2. Auditing
Identify what is broken. This produces broken_links.log and broken_links.json.
python ./scripts/03_audit_broken_links.py
3. Automated Repair
Always verify the git working tree is clean before this step (git status), so that git restore . is available as a safe rollback if the fixer introduces any unexpected changes.
Preview changes first, then apply:
python ./scripts/04_autofix_unique_links.py --dry-run
python ./scripts/04_autofix_unique_links.py --backup
Step 4 writes remaining_broken_links.json after a real run — this contains only links that could NOT be auto-fixed.
Note: --dry-run does NOT write remaining_broken_links.json. If you run Step 5 after a dry-run only, it will fall back to broken_links.json and show pre-fix data — Step 5 will print a notice explaining this.
Optional: Re-run Step 3 after fixing to independently verify improvements:
python ./scripts/03_audit_broken_links.py
4. Final Reporting
Generate the human-review report. Step 5 automatically uses remaining_broken_links.json if present (post-fix state), falling back to broken_links.json otherwise.
python ./scripts/05_report_unfixable_links.py
Review: Open unfixable_links_report.md to see items requiring manual intervention.
⚠️ Critical Rules
- Pipeline Order: Do NOT skip steps. Steps 1 and 2 must complete before Step 3, and Step 3 must complete before Step 4.
- Step 4 uses both files:
broken_links.jsondetermines which files to process;file_inventory.jsonis the basename lookup table. Ifbroken_links.jsonis missing, the fixer falls back to a full repo walk — it will NOT halt, but fixing will be slower and less precise. - Fixer scope: Step 4 only fixes markdown links
[label](path)and image links. Code path references in.py/.jsfiles (e.g.'./config.json') are audited by Step 3 but intentionally NOT modified by Step 4. Manually fix these or accept them in the report. - CWD matters: Run from the root of the repository you wish to scan.
- No Silent Failures: If a link is Ambiguous (multiple files with the same name), the tool will NOT fix it. You must check the Step 5 report and resolve it manually.
- Verify git state before fixing: Run
git statusto confirm a clean working tree before running Step 4. This ensuresgit restore .is a reliable rollback option.
📖 Progressive Disclosure
For detailed standards on what constitutes a "broken link" and common pathing pitfalls, see: Link Checking Standards
Maintained by the Agentic OS Quality Team