Skip to content

Documentation Review — Relevance & Correctness

A systematic, doc-by-doc review of every file under docs/ against the actual codebase, run on branch docs/okf-alignment (2026-06-20). High-confidence issues were fixed in place; everything requiring judgment is flagged below. Companion to the audit/roadmap and conventions guide.

Method & scope

All 170 docs (133 durable + 37 in superpowers/) were reviewed by area, each doc's concrete claims (file paths, namespaces, class/method/command names, config keys, CLI commands, table/column names, API shapes) verified against src/, sdk/, and config. Fixes were limited to safe, surgical, code-verified corrections (broken links/paths, renamed identifiers, wrong field/command names, demonstrably-wrong status: frontmatter). Anything needing a prose rewrite, restructure, or a judgment call was flagged, not edited. ADRs were treated as immutable records (links/frontmatter only).

At a glance

  • Durable docs (133): the large majority are accurate and current. ~30 carry a correctness issue or relevance concern (listed below). 16 fixes applied this pass.
  • superpowers/ (37): 36 are implemented or superseded point-in-time records; only ~4 retain live/reference value. Left unedited (historical snapshots); bulk-archive recommended.
  • Links: 555 relative links checked; 3 broken remain (all pre-existing, flagged). No breakage introduced.
  • Out of scope but urgent: apparent live credentials committed in src/Aspire/LBS.AspireHost/appsettings.development.json — see Security note.

Follow-up applied (2026-06-20): acting on this review, the 6 never-built Strapi/CMS ADRs (ADR-001…006) were deleted and the ADR index rebuilt; personal machine paths (/Users/mark/…) were scrubbed from the canonical-id note; and CurrentRoundScore→LiveScore was corrected in the two Ballr roster docs.

All P1 docs have since been rewritten/fixed to match current code (verified by file:line): generic-queries, the SuperCoach predictions API, scoreboard-tests, sporting-event, statsperform-nrl-scoreboard-importer, feed-importer-implementation (now "Admin Feed Imports"), discord-verification-frontend-implementation (React→SvelteKit, type→guide), deployment-pipeline-setup (app list), coding-standards and common-tasks (IQueryHandler signature, Marten-on-startup migrations, commit convention, dotnet run), and tradeassist-implementation (slimmed to an archived pointer). The P2/P3 items below have also been applied (tracked as LBS-1860) — SDK workflow refs, OC Array(Float64)→Array(Int32), architecture design reconciliation notes, Ballr API field corrections, dotnet test→dotnet run, removal of LBS.DatabaseMigrations references (Marten applies schema on startup), frontmatter reclassifications, and removal/repair of all broken links (link checker now reports 0 broken). A few items were intentionally left as historical/archived records (the storage-experiment evaluation docs and ADR-009 document the system as it was).

The appsettings credentials remain to be rotated (still open).

Fixes applied in this pass

File Change
developer-guide/event-history-viewer-backend.md LbsNamespace.InfrastructureQueries→CoreQueries; IRequiresUserContext→IRequireUserContext (verified GetAggregateEventsQuery.cs)
developer-guide/module-system.md using LBS.Domain.Infrastructure.Modules/Timers→LBS.Augment.Modules/Timers (×3)
developer-guide/timer-infrastructure.md using/Location → LBS.Augment.Timers / src/Core/LBS.Augment/Timers/
developer-guide/real-world-testing.md SuperCoach test path → AdelaideStrikersVsBrisbaneHeat_SuperCoachStatsValidation.cs
developer-guide/sdk/sdk-local-development.md .env VITE_API_URL→VITE_API_BASE_URL
getting-started/authentication-testing.md .env VITE_API_URL→VITE_API_BASE_URL
integrations/mcp-server.md SportingEventTools.cs→FixtureTools.cs
api/ballr/ballr-tradeassist-by-roster.md QueryType TradeAssistByRoster→GetTradeAssistByRoster
sport/mapped-players-query.md FoxFeedId→FoxId, NrlId→NrlPlayerId (table + JSON)
outcome-context/graphql-master-prompt.md filter idStartsWith→outcomeIdPrefix; categoryStartsWith: "GamePassing"→category: "QBPassing"
outcome-context/evaluations/storage-experiment/status.md fixed 2 broken samples/ links
plans/chat-participant-summary.md status: current→archived (work shipped)
plans/lbs-745-fixture-lineup-management.md status: current→archived (work shipped)
plans/match-live-response-contract.md status: current→archived (work shipped)
adr/deployment-operations.md removed leaked <function_calls>/TodoWrite block at EOF (AI-generation residue)

All edits were spot-checked against code; no systematic errors found.

Cross-cutting themes

  1. Design docs that outran the code. Several architecture/ and outcome-context/ design docs are forward-looking proposals that were later implemented with divergent names or not at all — they read as current but describe a different (or absent) reality. Worst: architecture/real-time-notification-system-technical-design.md (built, but proposed class/interface names differ from shipped).
  2. The Strapi / CMS feature was never built. ADR-001 through ADR-006 (adr-001-content-management-system-integration, event-sourcing-content-implementation, consumer-api-design, content-workflow-design, deployment-operations, strapi-integration-guide) describe a content stack with no corresponding code (no LBS.Domain.Content, no Strapi project, no /webhooks/strapi); the deployment ADR's K8s/AWS model contradicts the actual Azure Container Apps + Aspire setup.
  3. Infrastructure moved namespaces. Timers/Modules migrated from LBS.Domain.Infrastructure.* to LBS.Augment.* (src/Core/LBS.Augment/) — stale references fixed in the timer/module docs.
  4. A removed LBS.DatabaseMigrations project is still referenced as a setup/reset step in debugging.md, common-tasks.md, getting-started/README.md, and faq.md. Migrations now apply on app startup (Marten/Aspire) — these steps need rewriting once the current mechanism is confirmed.
  5. Stale IQueryHandler<T> examples. coding-standards.md and common-tasks.md show a IQueryHandler<TQuery> + 4-arg HandleAsync; the real interface is IQueryHandler<TQuery,TResult> with single-arg HandleAsync.
  6. dotnet test vs dotnet run. Multiple docs use dotnet test though the project mandates dotnet run for xUnit v3 (testing guides, common-tasks, debugging, real-world-testing, getting-started).
  7. Commit-convention drift. coding-standards.md / development-workflow.md prescribe feat:/fix: conventional commits, contradicting the lead-with-LBS-NNNN convention used in actual history.
  8. SDK publish workflow renamed. Docs cite publish-typescript-sdk.yml / publish-python-sdk.yml; SDK publishing is now in the unified Build-Container-Apps.yml.

Flagged for decision

P1 — misleading or operational (fix or supersede soon)

  • ADR-001…006 (Strapi/CMS): decide and record Rejected/Obsolete (feature never built). Today they read as Accepted.
  • developer-guide/generic-queries.md: entire generic GetAllQuery<TContract> API is obsolete — real types are non-generic records with ContractTypeName + Skip/Take/OrderBy. Needs rewrite.
  • api/ballr/get-player-super-coach-points-predictions-api.md: documents an invented request/response; real query takes only MatchId and returns Dictionary<string,double>. Needs rewrite or status: draft.
  • sport/scoreboard-tests.md: documents commands/events that don't exist (CreateScoreBoardCommand/ScoreBoardCreatedEvent…); real flow is SetScoreBoardDetailsCommand/ScoreBoardDetailsSetEvent, tests now span Cricket + RugbyLeague. Rewrite or archive.
  • sport/sporting-event.md: documents non-existent SourceId/SourceName/DataSource command fields and a fictional LuckBox-only projection branch.
  • importers/feed-importer-implementation.md: entire backend (IFeedProvider, browse queries, toggle command, FeedSyncTimerService) exists only in the doc; frontend shipped differently. Rewrite or archive.
  • importers/statsperform-nrl-scoreboard-importer.md: cites non-existent StatsPerformNrlMappingBuilder and an outdated ID-resolution chain (now IEntityMappingService).
  • integrations/discord-verification-frontend-implementation.md: documents a React build superseded by the actual SvelteKit implementation.
  • api/ballr/tradeassist-implementation.md: historical note citing renamed/moved classes, paths, output shape, and a removed QueryType; mark superseded by the per-endpoint docs.
  • developer-guide/deployment-pipeline-setup.md: wrong deployable-app list — lists a nonexistent McpServer target and omits Foundry-Web (+ its Cloudflare secrets).
  • developer-guide/coding-standards.md & common-tasks.md: stale IQueryHandler<T>/4-arg HandleAsync examples; commit-convention section contradicts LBS-NNNN.

P2 — correctness, lower blast radius

  • LBS.DatabaseMigrations references (debugging, common-tasks, getting-started/README, faq) — project removed; rewrite the setup/reset steps.
  • outcome-context/design.md & design-decisions.md: storage payloads described as Array(Float64); actual schema is Array(Int32). design.md mermaid also misplaces OutcomeCatalogMaterializer under Accumulation (it lives in LBS.OutcomeContext.Query/Discovery).
  • outcome-context/query-layer/reference.md: a living reference that points at the deleted LBS.Model.AmericanFootball.StorageExperiment/.../ClickHouseSchemas.cs; repoint to src/OutcomeContext/LBS.OutcomeContext.Storage/ClickHouse/.
  • SDK publish workflow refs (sdk-generation.md, sdk-generation-process.md) — point at non-existent per-language workflows.
  • developer-guide/sdk/sdk-generation-strategy.md: unresolved RFC whose recommendation was never adopted (TS SDK is committed); wrong Python path; garbled frontmatter description. Archive/supersede.
  • architecture/aggregates-events-and-commands.md: strong-typed-ID example uses StrongTypedIdBase class; real IDs are record struct … : IId.
  • architecture/real-time-notification-system-technical-design.md (names diverged), multihost-concurrency-design.md (distributed lock shipped, not via useDistributedLock), query-command-alignment-design.md (proposed registry/factory removal never done) — reconcile against shipped code.
  • api/ballr/get-team-rating-input-by-team-id-api.md: "Notes" misstate internals (direct LoadAsync + IMappedPlayersProvider, not GetSupercoachTeamByIdQueryHandler/AggregateRelations).
  • api/ballr/ballr-optimise-lineup-by-roster.md & ballr-tradeassist-by-roster.md: response field CurrentRoundScore is actually LiveScore.
  • api/ballr/ballr-tradeassist-input-by-teamid.md: documents a SalaryLeft request field the query lacks.
  • sport/mapped-players-query.md: field table still missing 5 fields and lists int/Guid? fields as string (names fixed this pass).
  • useNotifications React hook documented in developer-guide/notifications.md and sdk/typescript/README.md but has no SDK implementation.

P3 — convention / hygiene

  • dotnet test→dotnet run across testing guides, common-tasks.md, debugging.md, real-world-testing.md, getting-started/README.md.
  • runbooks/archive-non-luckbox-aggregates.md: calls its --apply/ArchiveOldAggregates.cs tool "non-existent" though it now exists; reconcile status/appendix.
  • samples/experiment-runs/README.md: "How to Reproduce" points at the deleted StorageExperiment project.
  • plans/match-live-response-contract.md: accurate reference mistyped type: plan (reclassify).
  • developer-guide/ownership-validation.md: a design-options spec mistyped type: guide; consider moving to adr/.
  • 3 broken links: clickhouse-schema-review.md→deleted ClickHouseSchemas.cs (rot); integrations/discord-integration.md→./api/, ./deployment/ (placeholder dirs that don't exist).

Security note (out of documentation scope)

The review incidentally surfaced apparent live credentials committed to src/Aspire/LBS.AspireHost/appsettings.development.json — including a Clerk SecretKey (sk_…), a Clerk WebhookSecret, a JWT signing Secret, two database passwords, an API key/secret pair, and an ApiKey beginning sk- next to an Anthropic DefaultModel (apparent live LLM key). (The Discord block on lines 79–86 holds YOUR_… placeholders.) Recommended: treat all committed values as compromised, rotate them, move secrets to user-secrets/environment variables, and consider scrubbing them from git history. Not actionable as a doc fix — flagged for immediate attention.

superpowers/ triage

The 20 specs/ and 16 plans/ (+1 note) are dated, point-in-time design artifacts. 36 of 37 describe work that has since shipped (verified by spot-checking the named code exists) — the V2 NFL FlowEngine series (SP2–SP5d + cleanups), the storage-experiment/streaming work (productionised as LBS.OutcomeContext.Storage), query-time sporting events, and the canonical-id/entity-resolution work. Only ~4 retain live value: specs/2026-04-16-nfl-outcome-id-catalogue.md (reference), specs/2026-05-20-canonicalize-name-free-deterministic-scheme-design.md (partial — deferred items), specs/2026-06-01-entity-resolution-de-decisions.md (open §B decision), specs/2026-06-09-engine-roster-extraction-design.md (newest; step 2 may be pending). Recommendation: bulk-mark the shipped 32 as status: archived (they currently carry no frontmatter; this is a deliberate follow-up, not done here).

Appendix — per-area coverage

Every doc was reviewed. Folders below are accounted for; only docs with an issue/flag are named (all others verified CURRENT + correct).

  • architecture/ (13): flags — real-time-notification-system-technical-design, multihost-concurrency-design, query-command-alignment-design, aggregates-events-and-commands, batch-command-design (unimplemented proposal). README lists a RugbyGameState aggregate that doesn't exist.
  • developer-guide/ (17): fixed — event-history-viewer-backend, module-system, timer-infrastructure, real-world-testing. flags — coding-standards, common-tasks, generic-queries, debugging, deployment-pipeline-setup, development-workflow, faq, notifications (useNotifications), ownership-validation (mistyped).
  • developer-guide/sdk/ (5): fixed — sdk-local-development. flags — sdk-generation, sdk-generation-process, sdk-generation-strategy.
  • getting-started/ (4): fixed — authentication-testing. flags — README (DatabaseMigrations, dotnet test). prerequisites/backend-local-setup excellent.
  • adr/ (11): flags — ADR-001…006 (Strapi/CMS never built); adr-007 stale generator name (LBS.Tools.TypeScriptGenerator→LBS.Tools.SdkGenerator); README index omits ADR-009 + notification ADR. Fixed — deployment-operations (leaked block).
  • api/ballr/ (11): fixed — ballr-tradeassist-by-roster. flags — get-player-super-coach-points-predictions-api, tradeassist-implementation, ballr-optimise-lineup-by-roster, ballr-tradeassist-input-by-teamid, get-team-rating-input-by-team-id-api.
  • importers/ (6): flags — feed-importer-implementation, statsperform-nrl-scoreboard-importer.
  • integrations/ (7): fixed — mcp-server. flags — discord-verification-frontend-implementation, clerk-webhook-implementation-plan (shipped), nuget-publish (source name).
  • models/ (8): all current/accurate. (nfl_sim_flowchart.md is generated — not edited.)
  • sport/ (5): fixed — mapped-players-query. flags — scoreboard-tests, sporting-event.
  • outcome-context/ (21): fixed — graphql-master-prompt, storage-experiment/status. flags — design, design-decisions, query-layer/reference, query-layer/build-plan (stale StorageExperiment paths in as-designed body). evaluations/* appropriately archived.
  • testing/ (4): flag — notification-system-testing-guide (dotnet test, .NET 9 pin). Bruno guides accurate.
  • runbooks/ (1): flag — archive-non-luckbox-aggregates (--apply now exists).
  • samples/ (4): flag — experiment-runs/README (reproduce path). Others are valid snapshots.
  • plans/ (3): all fixed to status: archived (work shipped); chat + lbs-745 carry post-rename identifier drift.
  • meta/ (3), root (4), user-guides/ (2), end-user-guides/ (1), usecases/ (1), configuration/ (1), data-engineering/ (1): current/accurate (security.md and data-engineering guide are exemplary).
  • superpowers/ (37): 36 implemented/superseded historical records; see triage above.

Generated from a 14-agent parallel review on branch docs/okf-alignment, 2026-06-20. Fixes verified against code; flags require human judgment.