logics-doc-fixer

name

logics-doc-fixer

description

Validate and repair Logics request/backlog/task/product/architecture docs (structure, indicators, and cross‑references) without deleting existing metadata. Use when Codex should audit `logics/request`, `logics/backlog`, `logics/tasks`, `logics/product`, or `logics/architecture` for missing sections/indicators, auto-update Progress from checkboxes, backfill linked refs when safe, or restore dropped indicator lines.

Logics Doc Fixer

Quick start

Run a dry scan first, then apply fixes:

python logics/skills/logics-doc-fixer/scripts/fix_logics_docs.py
python logics/skills/logics-doc-fixer/scripts/fix_logics_docs.py --write

To target specific docs:

python logics/skills/logics-doc-fixer/scripts/fix_logics_docs.py logics/request/req_001_example.md --write

What it fixes

• Ensures minimum indicators exist:
  • Requests: From version, Understanding, Confidence
  • Backlog/tasks: plus Progress
  • Product briefs: Date, Status, related refs, Reminder
  • Architecture docs: Date, Status, Drivers, related refs, Reminder
• Preserves all existing indicator lines (for example Status, Complexity, Theme, Reminder) and never removes them.
• Auto‑updates Progress from checkbox completion in # Plan (or # Acceptance criteria for backlog if checkboxes exist).
• Ensures required sections exist and adds placeholders when missing.
• Repairs references when possible:
  • Backlog item notes include Derived from the matching request (slug match).
  • Request # Backlog section lists derived backlog items (slug match).
  • Task # Context includes Derived from the matching backlog item (slug match).
  • Product briefs and architecture docs backfill matching Related ... refs when there is a unique slug match.

Options

• --write: apply changes (default is dry-run)
• --no-progress: do not auto-update Progress
• --repo-root: override repo root detection

Notes

• Matching is slug-based (e.g., req_005_my_feature ↔ item_012_my_feature).
• If multiple matches exist, references are not auto-added to avoid bad links.
• Safety rule: do not perform destructive rewrites of indicator blocks. If indicators appear missing after a previous run, restore from git history (HEAD) before any new edits.