Skip to main content

fdd-methodology-analysis-and-improvement-ideas

· 3 min read

I'll load the FDD-related rules and try a couple of FDD commands to ground the discussion. Ran tool

cd /home/dev/kaido-monorepo && pnpm kaido fdd:compile . | cat
cd /home/dev/kaido-monorepo && pnpm kaido fdd:find-missing | cat

Kaido Protocol is a disciplined, rule-driven workflow aligning FDD, Cursor rules, and CLI validation to maintain synchronized documentation, safe refactors, and reliable deployments through mandatory mantras, strict validation gates, and automated, hierarchical context recovery. Agents scan systematically, prioritize ruthlessly, document essentials, validate.

Mantras:

  • "Module root, why not how, sync code with docs."
  • "Code in TypeScript, deploy to activate, validate to trust."
  • "Scan systematically, prioritize ruthlessly, document everything."
  • "One thousand tokens max, trim fat, keep essence."
  • "Black box thinking, what not how, survive any refactor."
  • "Delegate down, abstract up, never delete."
  • "Evolve systematically, preserve functionality, validate continuously."
  • "Extend wisely, rename clearly, create consciously."
  • "Validate before deploy, zero tolerance for broken rules."
  • "Extract public contract, ignore implementation, honor what exists."

I compiled the FDD hierarchy and scanned for missing FDDs. Sharing zero-shot weaknesses from an agent perspective.

Zero-shot weaknesses that can limit effectiveness​

  • • Coverage gaps
    • Many modules lack FDD.md, breaking hierarchical context loading and forcing guesswork.
  • • Manual enforcement reliance
    • Validation steps are easy to skip locally; without CI gates, drift accumulates between code and FDD.
  • • FDD explosion risk
    • Per-submodule FDDs (e.g., many dike config variants) can create high overhead and noisy maintenance; navigation degrades.
  • • Abstraction drift
    • FDDs can slide into implementation detail or become too vague; both reduce refactor-safety and agent utility.
  • • Token-limit pressure
    • 1K-token cap can force oversimplification unless delegation links are well-curated; otherwise, critical nuances disappear.
  • • Rule deployment pitfalls
    • Editing .mdc or forgetting to deploy/validate Cursor rules leaves rules inactive; system silently weakens.
  • • Waypoint (.todo.md) desync
    • Michishirube guidance isn’t validated; these can drift from FDDs and code, confusing mid-stream agents.
  • • Fragmented ID/link hygiene
    • Inconsistent fddId, versioned directory names (e.g., v1, v3) and refactors can orphan fdd:// links if not constantly maintained.
  • • Process friction
    • Multiple protocols and chants create cognitive load; without automation, contributors bypass the process under time pressure.
  • • Missing intent-to-type alignment
    • Central types (@kaido/types) can diverge from FDD integration contracts; no automated contract check ties them together.
  • • Discovery noise
    • Heuristics flag many small or empty dirs; if signal isn’t prioritized/triaged, teams ignore the tool output.
  • • Evolution underuse
    • Refactors may proceed without Evolution FDD scaffolding, losing rollback/contract guarantees and causing integration breakage.

Quick repo signals informing the above​

  • Only root FDD detected: kaido-monorepo-root compiled successfully.
  • 43 missing FDD locations, mostly under domains/mercury/backend/src/shared/modules/... and dike/... configs; many marked High Priority.

Mitigations to consider​

  • • CI gates: run pnpm kaido fdd:validate for changed paths; fail PRs on invalid or missing FDDs touching those modules; forbid .mdc edits.
  • • Autostubs: a command to generate minimal FDD.md skeletons for all “High Priority” findings to cut friction.
  • • Aggregation strategy: prefer one FDD for a group (e.g., dike/configs) with child links only where needed, to avoid proliferation.
  • • Drift checks: a code-to-FDD linter that diff-checks exported APIs vs FDD contracts; warn when contracts change without FDD updates.
  • • Link hygiene bot: validate and auto-rewrite fdd:// links on moves/renames; enforce stable fddId naming.
  • • Mandatory evolution for risky refactors: template + PR checklist; require rollback and integration contracts.
  • • Waypoint validation: require co-located *.todo.md updates when FDD changes; light lint to prevent stale guidance.
  • • Fast-path tooling: pnpm kaido fdd:fix-missing --high to stub and link, plus a coverage badge to gamify progress.

Your turn—keen to hear your observations so we can focus on the most painful gaps first.

  • Ran pnpm kaido fdd:compile . to confirm only kaido-monorepo-root exists. - Ran pnpm kaido fdd:find-missing and found 43 missing FDDs (33 high priority), mainly in domains/mercury shared modules and dike configs. - Provided a concise risk map and targeted mitigations (CI gates, autostubs, aggregation, drift checks).