Skip to content
/ CoderLap
Docs

Three living files.

Plain markdown. Readable without the tool. The commands write to them; you read them like any other markdown.

Core
docs/DECISIONS.md
ADR log

Architectural Decision Records. Every trade-off that future-you will second-guess. Newest at top. Supersession explicit. Never deleted.

Each ADR captures
  • • Context
  • • Decision
  • • Alternatives considered
  • • Consequences + revisit-if
  • • Decider(s)

Written via /decision.

docs/KNOWN-ISSUES.md
recurring bugs

Non-obvious bug fixes with symptom, root cause, fix — and the prevention rule that stops recurrence.

The payoff

A good prevention rule is a permanent guard: a test, a type, a lint rule, a review checklist item. If you can't name one, the debugging isn't finished.

Added during /ship when you fix a non-obvious bug.

docs/SESSIONS.md
handoff log

Rolling log of session handoffs. Newest at top.

Each entry
  • • What shipped
  • • In flight (not yet shipped)
  • • Gotchas next session should know
  • • Next session should probably…

Written via /session.

Plus one

CLAUDE.md at the root.

Tells Claude how to work in this project. Loaded automatically every session.

Created by /before on first run, if missing. Your project-specific rules get added here.

Typical contents
  • ▸ The loop: /session last → /before → code → /ship → /session
  • ▸ Code principles (SR, DRY, CC, SoC)
  • ▸ Rules Claude follows (read before code, never add unrequested features, never delete history)
  • ▸ Absolute dates only · commit messages explain why · validate at boundaries
  • ▸ Anything project-specific (stack, commands, env)
Optional

Domain-specific gap files.

If a project area has a lot of missing pieces, create a per-area gap file. Totally optional — most projects don't need one.

docs/<AREA>-GAPS.md

Examples: docs/PARTNER-GAPS.md, docs/BILLING-GAPS.md.

Each gap has: Status (missing / partial / broken / shipped), Priority (P0–P3), Impact, Effort, Dependencies, Acceptance criteria. Closed gaps become shipped YYYY-MM-DD (commit: <hash>) — section stays for history.

Conventions

Boring naming. Forever stable.

Technical reference
architecture.md · api.md · components.md

Lowercase-kebab. Stable docs that evolve with the code.

Business / journey
BUSINESS-PLAN.md · TEAM-SUMMARY.md

UPPERCASE-KEBAB. Stakeholder-facing.

Gap (optional)
<AREA>-GAPS.md

Track missing features per domain.

Audit (immutable)
PROJECT-AUDIT-YYYY-MM-DD.md

Dated. Never overwrite — create a new file for a new audit.

Always use absolute dates.

Write 2026-05-01, never next Thursday. The record has to outlive the session that wrote it.