Skip to content
Dark Cosmos — Dev Docs

Whole-codebase review — 2026-09-29

Brief: whole-codebase review + short/medium/long-term plan (Dark Cosmos)

Section titled “Brief: whole-codebase review + short/medium/long-term plan (Dark Cosmos)”

Task type: research and planning. Docs only. Do NOT change game code, tests, project.godot, or BUILD. Branch: review-whole/2026-09-29 from origin/main. No merge, no PR, no deploy, do not touch main or the custom Godot fork.

Goal

Section titled “Goal”

A broad, evidence-based review of the ENTIRE repo, then concrete short-term (days), medium-term (weeks) and long-term (months) ideas, plans and improvements. Investigate every area; spin up sub-agents/workflows per area if your tools allow, otherwise work through areas sequentially. Depth over breadth per finding: every finding cites file:line or a measurement.

Read first

Section titled “Read first”

CLAUDE.md, docs/ROADMAP.md, docs/RELEASE-1.0.1.md, NEXT_TASKS.md, all of docs/architecture/*.md, docs/architecture/godot-gotchas.md, docs/reference/running-and-testing.md, dark-cosmos/README.md and role briefs. Already covered, build on and don’t repeat: docs/research/2026-09-29-general-performance-review.md, 2026-09-29-audio-performance-audit.md, 2026-09-28-code-cleanup-audit.md, 2026-07-04-bullet-heaven-genre-mechanics-survey.md, 2026-09-27-shop-economy-first-curve.md. Reference them, add only what is new.

Areas (one findings file each)

Section titled “Areas (one findings file each)”
  1. Sim core: sim/ (conductor size, module boundaries, determinism risks, purity violations, RNG-stream discipline, hot-loop cost).
  2. Weapons, mods, evolutions, buildcraft (balance outliers, dead/overlapping weapons, mod synergy holes).
  3. Enemies, bosses, spawn director, pacing, survival/story/tutorial modes.
  4. Meta-progression, shop, economy, unlock flow (retention loops, first-hour experience).
  5. Rendering, FX, shaders, UI, theming, accessibility (colour contrast, text sizes on TV, controller/focus navigation, reduced-motion).
  6. Input, controllers, touch, tvOS/iOS platform layer, co-op/pilots readiness.
  7. Telemetry, remote config, dev tools, Worker code in telemetry/ (privacy compliance vs site privacy page, retention, security, schema).
  8. Test suite and tooling: coverage gaps, flaky/slow tests, scripts/, CI/gate, release pipeline robustness, .claude/ skills/hooks/agents (stale, duplicated, missing).
  9. Docs and repo hygiene: stale docs, contradictions between CLAUDE.md/docs/code, dead code, asset bloat, gitignored-but-needed content.
  10. Product/market: what the game lacks vs peers (use the genre survey + web research), store-page/onboarding/retention opportunities, monetisation-adjacent ideas consistent with bullet-heaven-balance-philosophy (power grows across runs not within; no rubber-banding; no pay-to-win).
  11. Security and robustness: save-file handling, telemetry endpoints, secrets in repo, crash/edge cases.

Method rules

Section titled “Method rules”
  • Verify before asserting: read the code, run it (install Godot 4.7.1 stable Linux x86_64, godot --headless --import, run GUT, sim_bench/soak where useful). Tag every claim [Certain]/[Likely]/[Guessing]; if most of a section is guessing say so at the top.
  • Check “missing” things really are missing (grep the whole tree, git branch -a, git log) before proposing them. Note grep may be a ugrep shim that honours .gitignore; use /usr/bin/grep -r.
  • Do not invent design direction. Design forks are Chris’s call: present options with a recommendation and the risk of it.
  • Uncomfortable findings first in each file. Bugs found: list with repro, don’t fix.
  • EVE-style depth belongs in ~/Claude/sovereign, not here (bullet-heaven-sovereign-split). Don’t propose it as a mode.

Deliverables (all under docs/research/)

Section titled “Deliverables (all under docs/research/)”
  • 2026-09-29-whole-review/<area>.md per area above: findings, evidence, ranked ideas.
  • 2026-09-29-whole-review/README.md: index + method + what could not be checked.
  • 2026-09-29-whole-codebase-plan.md (needs a title: frontmatter block, the docs site requires it): synthesis. Three horizons (short: days; medium: weeks; long: months), each item with: what, why (evidence link), effort S/M/L, risk, dependencies, who (Chris design call / either dev / cloud-offloadable). Top 10 overall by value/effort. A “do not do” list. Suggested next 5 cloud briefs.
  • Do NOT edit NEXT_TASKS.md or RELEASE-1.0.1.md; list proposed additions in the plan instead.

Finish

Section titled “Finish”

Commit per area, push the branch. Final message: top findings, top 10 actions, what you could not verify, and what needs Chris’s decisions. Cap total length sensibly: dense tables and bullets, no filler.