Help us improve
Share bugs, ideas, or general feedback.
From aidoc-flow
Applies fixes to an ADR based on the latest audit report, covering structure, links, element IDs, content, references, and upstream drift. Use after an audit reports issues.
npx claudepluginhub vladm3105/aidoc-flow-framework --plugin aidoc-flowHow this skill is triggered — by the user, by Claude, or both
Slash command
/aidoc-flow:doc-adr-fixerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Read the latest audit report and apply fixes to an ADR, bridging
Runs structural checks and content review on ADR files, producing a combined quality report for downstream fix tools. Use as a quality gate before SPEC generation.
Validates ADR files in docs/adrs/ for reference integrity, supersedes/extends/related links, circular chains, self-references, and domain conflicts. Report-only or interactive fixes.
Writes Architectural Decision Records (ADRs) using the MADR template and verifies completeness with Definition of Done (E.C.A.D.R.) criteria. Use when documenting architectural decisions from meetings or PR discussions.
Share bugs, ideas, or general feedback.
Read the latest audit report and apply fixes to an ADR, bridging
../doc-adr-audit/SKILL.md and a passing ADR so the audit↔fix cycle can
converge.
Layer: 5 (ADR quality improvement).
Upstream: the ADR document + ADR-NN.A_audit_report_vNNN.md.
Downstream: the fixed ADR + ADR-NN.F_fix_report_vNNN.md.
After doc-adr-audit returns FAIL, as part of an Audit → Fix → Audit loop.
Do not use without an audit report (run the audit first) or to create a new
ADR (use ../doc-adr/SKILL.md / ../doc-adr-autopilot/SKILL.md).
Consume the latest ADR-NN.A_audit_report_vNNN.md. Back up the ADR before
editing (tmp/backup/ADR-NN_<ts>/); on error, restore. Element-ID standards
come from framework/governance/ID_NAMING_STANDARDS.md; structure rules from
framework/layers/05_ADR/ADR-TEMPLATE.yaml and README.md.
Run in order; later phases assume the earlier ones succeeded.
| Phase | Scope | Representative actions |
|---|---|---|
| 0 — Structure | nested-folder rule | move ADR into docs/05_ADR/ADR-NN_{slug}/; rename folder to match ID; fix relative links after the move |
| 1 — Missing files | referenced-but-absent | create glossary / index / reference placeholders from templates |
| 2 — Links | broken/abs paths | recompute relative paths; convert absolute → relative |
| 3 — Element IDs | legacy/invalid IDs | re-derive ADR.NN.SS.xxxx (section number + content hash); drop legacy ADR.NN.xxxx, numeric type-codes, DEC-XXX/ALT-XXX/CON-XXX prefixes; keep document refs in dash form ADR-NN |
| 4 — Content | placeholders, missing subsections | fill template dates; default missing status to Proposed; normalize subsection headings in place; flag [TODO]/[TBD] for manual completion |
| 5 — References | traceability | add missing cumulative tags @brd @prd @ears @bdd; add the @adr: ADR-NN self-tag and @depends: cross-links; update the ADR index |
| 6 — Upstream | metadata + drift | fix deliverable_type/document_type/status; apply tiered drift merge against changed upstream (BRD/PRD/EARS/BDD) |
Element ID re-derivation: key = "{doc_id}:{section_id}:{title}:{description}";
ID = ADR.{doc_id}.{section_id}.<first 4 hex of SHA256(key)> (extend to 8 on
collision). The element kind is conveyed by its section, not by a type-code.
Document-level refs (ADR-NN, SPEC-NN, IPLAN-NN) stay in dash form.
Tiered upstream drift: <5% change → Tier 1 auto-merge (patch bump); 5–15% →
Tier 2 auto-merge + detailed changelog (minor bump); >15% → Tier 3 archive
current + regenerate via autopilot (major bump). Never delete superseded
decisions — mark [SUPERSEDED] and retain for traceability. Record results in
.drift_cache.json.
Tag every applied fix and surface counts in the report:
| Confidence | Meaning |
|---|---|
auto-safe | deterministic, low semantic risk (link/path, header normalize, ID conversion) |
auto-assisted | template insertion with partial assumptions (scaffolded tables/subsections) |
manual-required | domain content cannot be inferred (unresolved TODO/TBD, decision rationale) |
Write ADR-NN.F_fix_report_vNNN.md with: Summary (issues in / fixed /
remaining; files created / modified) · Fixes Applied (code, issue, fix,
file, confidence) · Manual-Review Queue · Validation After Fix
(score/errors/warnings before→after) · Cleanup Summary (delete superseded
fix reports) · Next Steps (re-run doc-adr-audit). Loop until score ≥
threshold or max iterations reached.
Before applying fixes, read the project adaptation profile
(.aidoc/profile.yaml). Honor section_toggles: do not reintroduce an
optional section the project has toggled off. Ignore any unknown or
out-of-surface key.
Authority: framework/governance/ADAPTATION.md.
../doc-adr-audit/SKILL.md · Create: ../doc-adr/SKILL.md../doc-adr-autopilot/SKILL.md · IDs: ../doc-naming/SKILL.mdframework/layers/05_ADR/ADR-TEMPLATE.yaml,
framework/governance/ID_NAMING_STANDARDS.md