CLAUDE.md Review & Upgrade

Date: 2026-03-20

Background

The CLAUDE.md hierarchy has grown organically and needs a focused audit. The global file carries KB-business workflow rules that don’t belong globally. The monorepo file is good but lacks sd-app awareness. There is no apps/sd-app/CLAUDE.md at all — meaning every SD App implementation session starts without the LevPro port context, TDD requirements, or architectural decisions.

Files in Scope

File	Status	Action
~/.claude/CLAUDE.md	Overgrown — contains KB-specific rules	Prune to universal-only
_WorkingOn/CLAUDE.md	Well-scoped	Light review only
~/projects/monorepo/CLAUDE.md	Good	Add sd-app awareness note
apps/sd-app/CLAUDE.md	Does not exist	Create

Tasks

1. Audit global ~/.claude/CLAUDE.md

Read the file. For each section, ask: “Does this apply to every project I will ever work on, or just KB/Business?”

Rules that belong globally:

• Strategic partner directive
• Hard rules (never guess, SSOT, etc.)
• Task execution philosophy + testing standards
• Coaching directive
• Tool selection principle
• Environment (WSL, paths)
• Git conventions
• Skills quality standard

Rules to move or remove:

• KB task/session workflow details → already in _WorkingOn/CLAUDE.md; remove duplicates from global
• Any reference to specific KB folder paths → not global
• Task file format / SMTM references → belong in _WorkingOn/CLAUDE.md only

Goal: global file should apply equally well to a completely different project.

2. Light review of _WorkingOn/CLAUDE.md

Read the file. Verify it contains everything removed from global. No structural changes expected — this file is well-scoped.

3. Add sd-app awareness to monorepo/CLAUDE.md

Add a brief section (5–10 lines) pointing to the SD App sub-project:

## SD App (`apps/sd-app/`)

The SD App is a SvelteKit PWA for leveraged investing analysis. It has its own
`CLAUDE.md` at `apps/sd-app/CLAUDE.md` with project-specific rules. Read that
file before working in `apps/sd-app/`.

4. Create apps/sd-app/CLAUDE.md

Create a new file covering everything an implementation session needs to know about the SD App without re-reading task history. Include:

Project Identity

• Name: $MART DEBT App
• Purpose: Port Talbot Stevens’ LevPro (VB6) leverage analysis software to a modern SvelteKit PWA
• Primary constraint: adapter-static (Cloudflare Pages) — all math runs client-side in TypeScript, no backend server in Phase 1

Non-Negotiable Rules

• The VB6 source code is the authoritative specification for all math
• Never invent math — every calculation must trace to a specific VB6 line
• Never implement a calculator until golden fixtures from LevPro are captured and tests are written first (TDD)
• All math must pass golden-fixture tests before any frontend work begins

Architecture

• Math engine: TypeScript classes in src/lib/calculators/ca/ (following CanadaTaxCalculator pattern)
• Fixtures: src/lib/calculators/fixtures/ — JSON files, values from LevPro outputs
• Tests: Vitest (pnpm test from apps/sd-app/)
• Routes: /[country]/[lang]/[calculator]/ — only ca/en active in Phase 1
• UI components: button, card, input, label in src/lib/components/ui/
• Formatting: formatCurrency() in src/lib/formatters.ts
• Profile store: src/lib/stores/profile.svelte.ts (country, province, marginalTaxRate)

Phase Status

• Phase 1 plan: D:\FSS\KB\Business\_WorkingOn\Tasks\2026-03-20_SD-App-Phase1-Plan.md
• Current phase: Phase 1 — Interest-Only Projections (Canada)
• Blocking pre-conditions: (A) VB6 source study complete, (B) LevPro fixtures captured

Key Decisions (Locked)

• TypeScript math (not Python) for Phase 1 — deferred to Phase 2 for historical data pipeline
• “Better Than” return is the hero output of every calculator
• 3-scenario results table (conservative / moderate / optimistic) is the standard display pattern
• Python backend deferred to Phase 2 (historical data pipeline)

Testing

• Unit tests: Vitest (pnpm test)
• E2E: Playwright (configured at monorepo level for Template site; sd-app E2E TBD)
• Never report a calculator complete until all golden fixtures pass

Verification

After all changes:

1. Read each file back — confirm it contains only what it should
2. Check for duplicates across files (same rule in two places = pick one, delete the other)
3. Run a quick sanity check: open a hypothetical “fresh implementation session” mentally — does reading just apps/sd-app/CLAUDE.md give enough context to start Phase 1 without reading any task history?

---

Claude Response — 2026-03-20

Summary

• Pruned ~/.claude/CLAUDE.md — removed “Task & Note Management System” section (lines 291–326); all other sections intact
• Reviewed _WorkingOn/CLAUDE.md — task file workflow rules confirmed present; no changes needed
• Added SD App section to monorepo/CLAUDE.md — inserted before ## Code Style
• Created apps/CLAUDE.md — stack, shared resources, testing, per-app CLAUDE.md index
• Created apps/sd-app/CLAUDE.md — project identity, non-negotiable rules, architecture, phase status, locked decisions, commands

Verification

• ~/.claude/CLAUDE.md — “Task & Note Management System” section confirmed absent; Git Conventions section intact
• monorepo/CLAUDE.md — SD App section confirmed present
• apps/CLAUDE.md — 4 sections present
• apps/sd-app/CLAUDE.md — 6 sections present
• _WorkingOn/CLAUDE.md — task file rules confirmed present, no changes made

Files Changed

File	Action
~/.claude/CLAUDE.md	Removed KB-specific task workflow section
/home/ta/projects/monorepo/CLAUDE.md	Added SD App section
/home/ta/projects/monorepo/apps/CLAUDE.md	Created
/home/ta/projects/monorepo/apps/sd-app/CLAUDE.md	Created

Next Steps for Talbot

• Review apps/sd-app/CLAUDE.md — confirm the locked decisions and phase status are accurate
• Git commit in monorepo for the new CLAUDE.md files

Talbot Response

---