apply-best-practice-driven-development

name	apply-best-practice-driven-development
description	Use when the user wants to systematically align any project or artifact to their stated best practice preferences — e.g., "apply BPDD", "align this project to our settings", "close the gap between our practices and reality", "enforce our best practices like TDD".
source	Beck (2003) "Test-Driven Development: By Example"; Ford, Parsons, Kua (2017) "Building Evolutionary Architectures"; Nagappan et al. (2008) "Realizing Quality Improvement Through Test Driven Development", IEEE
tags	["bpdd","tdd","compliance","enforcement","cycle","preferences","settings","domain-agnostic"]
related	["check-best-practice-compliance","pin-best-practice-preference","apply-best-practice-profile","review-best-practice-fit"]

Apply Best Practice Driven Development

Systematically align any project or artifact to its stated best practice preferences using a Red-Green-Refactor cycle driven by grimoire.toml and profiles. Works for codebases, legal documents, business plans, training programs, marketing campaigns — any work product with declared practices.

Why This Is Best Practice

Adopted by: Architecture fitness functions (Ford, Parsons, Kua — "Building Evolutionary Architectures", O'Reilly 2017) encode quality criteria as executable checks and validate continuously — the same inversion as TDD: define the check before the implementation. Netflix, Thoughtworks, and Amazon use fitness functions to enforce architectural constraints at CI time. The same principle applies beyond code: quality management systems (ISO 9001) and legal compliance frameworks define compliance criteria before auditing against them. Impact: Without BPDD, teams apply best practices opportunistically — gaps accumulate and preferences drift silently from reality. TDD reduces defect density 40–80% (Nagappan et al., IEEE 2008) not because tests catch bugs, but because the write-test-first discipline prevents gaps from forming. BPDD applies the same mechanism to best practices across any domain. Why best: review-best-practice-fit identifies gaps reactively, after implementation. BPDD inverts this: the preferences declared in settings are the specification; the artifact follows. The cycle continues until artifact and spec agree — leaving no gaps to discover later.

Sources: Beck (2003) "Test-Driven Development: By Example"; Ford, Parsons, Kua (2017) "Building Evolutionary Architectures"; Nagappan et al. (2008) "Realizing Quality Improvement Through Test Driven Development"

Steps

1. Resolve the effective spec (silent)

Grimoire-first (preferred): If grimoire MCP is connected, call grimoire_context — do NOT manually re-read settings files. resolved_profiles contains the fully expanded skill list per profile (5-step file search + 4-layer composition already applied). domain_sections has per-domain practices, thresholds, and fallback. settings_sources has per-field source attribution. Use these as the authoritative resolved spec.

If CLI only (no MCP): run grimoire context --json or grimoire settings and read the same fields.

Fallback (grimoire not installed): Read all settings layers in precedence order:

session pins
  ↓ overrides
grimoire.toml          (local — committed, --local)
  ↓ overrides
~/.config/grimoire/grimoire.toml (global — per-user, --global)
  ↓ overrides
/etc/grimoire/grimoire.toml      (system — machine-wide, --system)

• Expand profiles = [...] to skill lists (tag query or file)
• Apply domain overrides ([standards.engineering.architecture] overrides [standards.engineering])
• Apply disabled entries — remove those skills from the spec
• Drop any practice overridden by a higher-precedence layer

Empty spec guard: If the resolved spec contains zero practices (all domains empty or settings file missing), stop immediately. Do not proceed to Step 2. Output: "No practices are configured. Run /pin-best-practice-preference or /apply-best-practice-profile to set preferences first, then retry BPDD."

---

2. Show the resolved spec

Display the effective spec before running — the user must see what they're aligning to:

Effective spec — 5 practices

  apply-solid-principles       [profile: oop → grimoire.toml]
  apply-domain-driven-design   [profile: oop → grimoire.toml]
  apply-kiss-principle         [standards.engineering.architecture → global]
  apply-pyramid-principle      [writing → grimoire.toml]
  audit-gdpr-compliance        [standards.law → global]
  ⊘ apply-law-of-demeter       [disabled by grimoire.toml]

If settings are empty, stop and direct user to pin-best-practice-preference or apply-best-practice-profile first. Otherwise, proceed automatically — user invoked BPDD explicitly, no confirmation needed. The source tags in brackets ([profile: oop → grimoire.toml]) come from settings_sources in grimoire_context output — read them directly, do not infer.

---

3. Select scope

Scope:
  [s] Specific artifact   — a file, document, section, or component
  [r] Region / scope      — a directory, chapter, module, or area
  [c] Changed only        — diff-based, checks only modified parts
  [a] Full project        — everything in scope of the settings

---

4. Run compliance check

Call check-best-practice-compliance against the selected scope using the resolved spec. Read coverage.details[] from the JSON output to classify each practice — do not recompute per-practice scores by grouping diagnostics:

• PASS — details[].failing == 0 and details[].partial == 0
• PARTIAL — details[].partial > 0 and details[].failing == 0
• FAIL — details[].failing > 0

Compliance baseline

  ✓ apply-kiss-principle          PASS     (3/3 criteria)
  ✗ apply-solid-principles        FAIL     (2/5 criteria, 40% coverage)
  ~ apply-pyramid-principle       PARTIAL  (2/3 criteria, 67% coverage)
  ✗ apply-domain-driven-design    FAIL     (0/4 criteria, 0% coverage)
  ✓ audit-gdpr-compliance         PASS     (5/5 criteria)

Overall: 55.0% criteria coverage  ·  threshold: 80%  ·  STATUS: FAIL
2 passing · 2 failing · 1 partial

If all pass and threshold met: codebase already aligns with spec. Report and stop.

---

5. Pick next gap

Priority order (explicit, shown to user):

1. Blocking practices (fix these first) — a practice is blocking when: (a) its coverage.details[].coverage_pct is the lowest among all FAILing practices, AND (b) if it were to pass, overall coverage would meet or exceed the threshold. Compute: (passing_criteria + details[].total) / total_criteria × 100 ≥ threshold. If multiple practices meet this condition, fix the one with lowest coverage_pct first.
2. FAIL before PARTIAL
3. Within same status: settings array order (index 0 = highest priority)
4. User override: "fix X next" accepted at any point in the cycle

Next: apply-solid-principles (FAIL, 40% coverage)
  Reason: causing threshold failure + listed before apply-domain-driven-design

  ✗ SRP: UserService handles auth, email, and billing (3 concerns)
  ✗ DIP: direct dependency on MySQLUserRepository
  ✓ OCP, LSP, ISP — already passing

---

6. Green — implement

Read the "practice" field from each failing diagnostic in the JSON report — that value is the grimoire skill to invoke. "practice": "apply-solid-principles" → /apply-solid-principles; "practice": "apply-domain-driven-design" → /apply-domain-driven-design; and so on. Re-run check-best-practice-compliance for this practice after each change until it passes.

---

7. Refactor

Clean up the implementation while keeping the check green. Re-run to confirm no regression.

---

8. Commit

If no changes were made during this BPDD cycle (all criteria passed), skip the commit step entirely. If changes were made, commit message format: fix(bpdd): align [artifact/scope] to [practice-name] preferences. Return to step 5 for the next failing practice. Continue until all practices pass and threshold is met.

---

9. Final report

✓ BPDD complete — 5/5 practices aligned  ·  92% criteria coverage

  ✓ apply-solid-principles      (fixed: 3 violations resolved)
  ✓ apply-domain-driven-design  (fixed: domain model extracted)
  ✓ apply-pyramid-principle     (fixed: 1 remaining gap closed)
  ✓ apply-kiss-principle        (was already passing)
  ✓ audit-gdpr-compliance       (was already passing)

Threshold: 92% ≥ 80% ✓
Artifact now aligns with grimoire.toml

Ongoing:
  grimoire watch              # re-checks on every file save (local dev)
  grimoire status             # project health at a glance
  grimoire check --ci         # CI gate (auto-annotates GitHub Actions)

Common Mistakes

Running BPDD without reviewing the resolved spec first. Always show step 2 — the user must confirm what spec they're aligning to. A misconfigured settings file means fixing the wrong things.

Skipping commit between cycles. Each Green must be committed before moving to the next practice — same discipline as TDD.

Ignoring suppressed findings. Suppressed violations (via # grimoire-ignore) still appear in the JSON report. Review them periodically — suppressed ≠ resolved.

When NOT to Use

• For one-time review — use review-best-practice-fit instead; BPDD is for systematic, committed alignment
• When grimoire.toml is empty — set preferences first with pin-best-practice-preference or apply-best-practice-profile