simplify-then-add-lightness-audit

Files (2)

• SKILL.md
• references.bib · references/

SKILL.md (first lines)

# SOP: Simplify-Then-Add-Lightness audit

One-command codebase audit using verbalized sampling \[zhang2025verbalized\]
against the Colin Chapman principle encoded in the project ADR
\[vsekaisimplify2026\].

## 0. Read the ADR (once per session)

Fetch the current ADR so the audit stays anchored to it:

```
/fetch https://v-sekai.github.io/manuals/decisions/20260422-simplify-then-add-lightness.html
```

Key tests from the ADR to apply to every candidate:

- Would a new engineer need to understand this to ship?
- Does it add a release obligation (version string, hash, formula) with no
  production payoff?
- Is there a simpler thing already present that does the same job?
- Does it couple two systems that should be independent?

### Strategic Delegation — mandatory pre-filter

Before scoring any candidate, classify it:

- **Core uncertainty** (defines whether the project works at all — character
  motion, UX interaction, spatial partitioning, transport protocol): these stay
  in-house regardless of commit count or consumer count. Do not nominate them.
- **Mature, well-understood component** (databases, S3 storage, OS libraries,
  external game APIs): these are delegation candidates.
- **License-constrained fork** (e.g. BSL-licensed upstream replaced by own
  build): the fork is load-bearing by compliance necessity. Do not nominate it
  for removal without a licence-compatible replacement already in hand.

Known permanent exclusions for this repo:

| Submodule | Reason to keep |
|---|---|
| `cockroach` | BSL licence on upstream — own build is the compliant alternative |
| `multiplayer-fabric-humanoid-project` | In-house character motion research (core uncertainty) |
| `multiplayer-fabric-interaction-system` | In-house UX/XR interaction research (core uncertainty) |
| `multiplayer-fabric-artifacts-mmog` | Taskweft test harness on a stable external platform — validates the planner before the home platform is ready (Risk Sequencing) |
| `multiplayer-fabric-rx` | Integration environment validating the full Godot stack (VRM, XR, game framework, humanoid) works together — core uncertainty for stack cohesion |
| `multiplayer-fabric-baker` | Godot asset baker — should feed into desync for storage; missing integration is a bug, not dead weight |
| `multiplayer-fabric-desync` | Content-addressed storage (casync) — intended storage backend for baker output; keep until baker→desync integration is complete |
| `multiplayer-fabric-sandbox` | Proof-of-concept UGC programming language (RISC-V sandbox) — core uncertainty for user-generated content runtime |
| `multiplayer-fabric-webtransport` | Vendored fork — upstream requires patches that cannot be upstreamed; own build is the only viable option |
| `multiplayer-fabric-skills` | Project SOP library — Claude Code skills evolve with the codebase; removing it severs the process documentation from the code it governs |
| `multiplayer-fabric-predictive-bvh` | Codegen source for `multiplayer-fabric-godot/thirdparty/misc/predictive_bvh.h` — the fabric cannot run without this generated header |
| `ZoneConsole.AccessKit` (`zone-console/lib/zone_console/access_kit.ex`) | Planned integration point for native accessibility tree (NSAccessibility / AT-SPI2 / UI Automation) — needs plumbing into Godot, zones, and backends; stub + test are forward scaffolding, not dead weight |
| `Uro.IdentityProofController` + `Uro.UserRelations` identity_proof functions | Planned web-of-trust feature — to be wired via ReBAC (Taskweft.ReBAC) with HTTP routes; unrouted now but not dead weight |
| `Uro.Uploaders.UserIcon` (`zone-backend/lib/uro/uploaders/user_icon.ex`) | Planned Waffle→S3→desync upload integration — needs wiring to S3 bucket and desync chunk store; zero callers now but load-bearing once the upload pipeline is wired |
| `Uro.EnsureUserNotLockedPlug` (`zone-backend/lib/uro/plug/ensure_user_not_locked_plug.ex`) | Planned account-lock security check — to be wired into router pipelines once account locking is implemented; not dead weight |
| `ZoneConsole.FabricMMOGKeyStore` (`zone-console/lib/zone_console/fabric_mmog_keystore.ex`) | Planned AES-128 asset key store for the baker encryption pipeline (`encrypt_pck` currently disabled); uses OS keychain (correct — zone-console has no DB); Elixir port of `modules/keychain/fabric_mmog_keystore.cpp`; not dead weight |
| `Taskweft.HRR.*` (`multiplayer-fabric-taskweft/lib/taskweft/hrr/`) | Per-entity episodic memory for the RECTGTN HTN planner. Each persona owns its own episodes (source = "entity:{uuid}") — personas do not share bodies or memories. One SQLite file per zone holds all entities' namespaces. Integration: probe entity memory → inject top-k episodes into domain state → plan → store result. Cross-entity learning is opt-in only. Placement: alongside the zone process (not zone-backend/CRDB). Do not remove even with zero callers. |

## 0.5. Stall check — when simplification alone is not unblocking progress

If the user reports the project is still not moving after repeated removal runs,
shift the distribution framing from **dead-weight removal** to
**feedback loop compression** (ADR principle: Feedback Loop Compression +
Sequence Risks).

Run these additional checks before generating the distribution:

```sh
# Commit velocity per submodule — last commit date
for mod in <submodules>; do
  git -C $mod log -1 --format="%ar %s"
done

# Are critical-path services gated behind optional profiles?
grep -n "profiles:" <docker-compose files>

# Are e2e / smoke tests wired to CI, or manual-only?
find . -maxdepth 4 -name "*.spec.ts" -o -name "*e2e*" | grep -v ".git"
grep -r "playwright\|cypress\|smoke" .github/workflows/ 2>/dev/null

# Are core integrations wired? (e.g. baker→desync, zone-server→CI)
# For each pair of related submodules, grep each for the other's name
```

The slowest feedback loop is the gap between "engineer makes a change" and
"the critical assumption (e.g. players can connect) is verified." Identify it
from git history: look for active repos with zero cross-references, optional
service profiles, and e2e tests that only run manually.

Reframe the distribution task when stalled:

```
name ONE barrier to remove that would compress the feedback loop between
a code change and verifying the critical assumption. "Remove" includes:
removing an optional-profile gate, removing dead config that hides service
health, or removing the isolation between two systems that must be wired.
Flag candidates that are actually ADDs disguised as removals — those require
deliberate addition, not removal.
```

Return to standard removal framing once the critical feedback loop is closed.

## 1. Inventory the codebase

Run these before generating the distribution so weights are grounded in facts,
not assumptions:

```sh
# Active submodules
git submodule status

# Dead files (bak, build artefacts, committed test output)
find . -maxdepth 4 \( -name "*.bak" -o -name "test-results" -o -name "docs.bak" \) \
  -not -path "./.git/*" -not -path "./*/\.git/*"

# Placeholder / never-shipped release manifests
grep -r '"0000000000000000000000000000000000000000000000000000000000000000"' \
  --include="*.rb" --include="*.json" -l 2>/dev/null

# Submodules with no consumers (nothing imports them)

From V-Sekai-fire/contract-multiplayer-fabric-skills, MIT.

More from V-Sekai-fire/contract-multiplayer-fabric-skills