Skip to content

Documentation Methodology — Keeping docs/ a Single Source of Truth

This runbook defines how the docs/business-logic/ and docs/technical/ files are produced and kept accurate. Any agent (or person) updating these docs MUST follow it. It exists because docs written from memory/inference across three codebases silently drift. The cure is not better writing — it is verification-first authoring with traceable proof.

The four guardrails (non-negotiable)

  1. No untraced claims. Every rule stated as fact in a technical file MUST carry a source anchor pointing at the backend code (or migration / cron / DB table) that proves it. If a claim cannot be traced, it does not get stated as fact — it goes into the file's "Known limitations / open questions" note.
  2. Cross-reference before concluding; backend wins. Never state a business rule from a single vantage point. Before concluding, check all three sources — the backend controller/ helper (source of truth), the app's use of it, and the admin's use of it — and reconcile them. Only after they've been cross-referenced do you write the rule. aashray-backend is authoritative: when the app or admin behaves differently, document the backend behavior and explicitly note the client divergence. Never document a rule from the app/admin alone, and never conclude from the backend alone without confirming how the clients actually exercise it.
  3. Business-logic is derived, never authored independently. The plain-language business-logic/NN-*.md file is a projection of the already-corrected technical/NN-*.md file. Write/verify the technical file first, then rewrite the business file from it. This is why the code-free file cannot drift on its own.
  4. Data-driven facts are checked against the live DB. Enum values in use, config rows, and thresholds stored in the database (not in code) are verified with the aashray DB MCP, not assumed from code defaults.

The source-anchor convention

Every discrete rule in a technical/NN-*.md file ends with a greppable citation:

  • Code: [src: aashray-backend/<path>:<line>] (line optional but preferred)
  • Multiple sources: [src: a.js:10; b.js:44]
  • Migration / schema: [src: migrations/<file>] or [db: <table>.<column>]
  • Cron / scheduled: [src: aashray-backend/cron/<file>]
  • Verified against live data: append [db-verified: <table>]

Business-logic files stay clean — no anchors, no code identifiers.

The per-domain loop

Run this for one domain at a time, get sign-off, then move to the next.

  1. Map the surface. Use the knowledge-graph MCP (semantic_search_nodes, query_graph with callers_of/callees_of/imports_of/tests_for, get_affected_flows) to enumerate the backend controllers, models, routes, and cron that own the domain. This list is the ground truth of what the domain actually consists of.
  2. Extract claims. Turn the current technical + business files into a flat checklist of every discrete claim: each price, cutoff, day-count, status transition, validation, refund/credit rule, and cron behavior.
  3. Verify each claim. For each, read the actual backend code the graph points to (and the live DB for data-driven facts). Mark it:
  4. ✓ correct
  5. ✗ wrong — record the corrected value + source
  6. ⚠ unverifiable — becomes an open-questions note, never stated as fact
  7. Correct in place. Fix the technical file and attach a source anchor to every rule. Then re-derive the business-logic file from the corrected technical file.
  8. Checkpoint. Human review of the corrected domain before starting the next.

Verification order (hubs before spokes)

Everything references the hubs, so verify them first:

01 architecture → 03 booking engine → 08 payments → 13 status/cron
  → 04 stay → 05 food → 06 travel → 07 adhyayan/utsav
  → 02 accounts → 09 services → 10 notifications

Re-auditing later (the payoff of anchors)

Because every rule is anchored to a backend file, a future audit is cheap and mechanical:

  1. Ask the graph MCP detect_changes (or use git) for backend files changed since the last verification date.
  2. grep the technical docs for anchors pointing at those files.
  3. Re-verify only those rules. Everything else is still proven.

This is what keeps the docs a living single source of truth instead of a one-time snapshot.