Help us improve
Share bugs, ideas, or general feedback.
From aidoc-flow
Fixes a BDD suite from the latest doc-bdd-audit report: structure, links, element IDs, Gherkin 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-bdd-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 a BDD suite, bridging
Audits a BDD suite with declarative structural checks and content-quality review, producing a combined report for doc-bdd-fixer. Use before ADR generation or inside the audit↔fix cycle.
Validates acceptance tests against AAID BDD quality criteria, checking three-layer architecture, isolation, state management, and stubbing. Produces pass/warn/fail table.
Receives bug reports from QA agents and implements focused, minimal fixes. Works with any tech stack.
Share bugs, ideas, or general feedback.
Read the latest audit report and apply fixes to a BDD suite, bridging
../doc-bdd-audit/SKILL.md and a passing BDD so the audit↔fix cycle can
converge.
Layer: 4 (BDD quality improvement).
Upstream: the BDD document + BDD-NN.A_audit_report_vNNN.md.
Downstream: the fixed BDD + BDD-NN.F_fix_report_vNNN.md.
After doc-bdd-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
BDD (use ../doc-bdd/SKILL.md / ../doc-bdd-autopilot/SKILL.md).
Consume the latest BDD-NN.A_audit_report_vNNN.md. Back up the BDD before
editing (tmp/backup/BDD-NN_<ts>/); on error, restore. Element-ID standards
come from framework/governance/ID_NAMING_STANDARDS.md; structure and Gherkin
rules from framework/layers/04_BDD/BDD-TEMPLATE.yaml and README.md.
Run in order; later phases assume the earlier ones succeeded.
| Phase | Scope | Representative actions |
|---|---|---|
| 0 — Structure | folder/index rule | move BDD into docs/04_BDD/BDD-NN_{slug}/; rename folder to match ID; ensure index present; fix relative links after the move |
| 1 — Missing files | referenced-but-absent | create glossary / index / .feature placeholders from templates |
| 2 — Links | broken/abs paths | recompute relative paths; convert absolute → relative |
| 3 — Element IDs | legacy/invalid IDs | re-derive BDD.NN.SS.xxxx (section + content hash); drop legacy BDD.NN.xxxx, numeric type-codes, SCEN-XXX/STEP-XXX prefixes |
| 4 — Content | placeholders, tags, thresholds | fill template dates; move comment tags to Gherkin-native; add @scenario-type/priority/WITHIN thresholds; flag [TODO]/[TBD] and missing Given-When-Then for manual completion |
| 5 — References | traceability | add missing cumulative @brd @prd @ears tags; fix cross-doc paths; add/repair spec_trace; update the traceability matrix |
| 6 — Upstream | metadata + drift | fix deliverable_type/document_type/upstream_mode; when upstream EARS drifts, apply tiered drift merge (below) |
Element ID re-derivation: key = "{doc_id}:{section_id}:{title}:{description}";
ID = BDD.{doc_id}.{section_id}.<first 4 hex of SHA256(key)> (extend to 8 on
collision). Document-level refs (SPEC-NN, ADR-NN, IPLAN-NN) stay in dash
form; scenarios live in section 03.
Content-preservation in Gherkin: never modify step text (Given/When/Then) or
Examples-table data; only add missing tags/metadata and replace hardcoded values
with @threshold: references. Missing keywords/structure are flagged, not
invented.
Tiered upstream drift (EARS changed since BDD): <5% change → Tier 1
auto-merge new scenarios (patch bump); 5–15% → Tier 2 auto-merge + detailed
changelog, mark modified-source scenarios for review (minor bump); >15% → Tier 3
archive current + regenerate via autopilot (major bump). Never delete
upstream-removed scenarios — mark @deprecated 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, tag relocation, ID conversion, threshold substitution) |
auto-assisted | template insertion with partial assumptions (scaffolded scenarios/sections, default priority tags) |
manual-required | domain content cannot be inferred (unresolved TODO/TBD, missing Given-When-Then, step semantics) |
Write BDD-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-bdd-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-bdd-audit/SKILL.md · Create: ../doc-bdd/SKILL.md../doc-bdd-autopilot/SKILL.md · IDs: ../doc-naming/SKILL.mdframework/layers/04_BDD/BDD-TEMPLATE.yaml,
framework/governance/ID_NAMING_STANDARDS.md