MBR KB (D:\FSS\KB\MBR\) — part of the unified vault at D:\FSS\KB\. Cross-business content lives in Core\. Architecture: Core\CONSTITUTION.md. SMTM guide: D:\FSS\KB\Core\Processes\Simple Markdown Task Management\SMTM_System.md.

KB Task & Note Management — Claude Code Instructions

Full guide: D:\FSS\KB\Core\Processes\Simple Markdown Task Management\SMTM_System.md

Location

WSL Path: /mnt/d/FSS/KB/MBR/_WorkingOn/ Windows Path: D:\FSS\KB\MBR\_WorkingOn\

Folder Structure

_WorkingOn/
├── Tasks/
│   ├── _tmp.md                  # Scratch file for quick/temporary tasks
│   ├── Tasks-Template.md        # SSoT template for task files
│   └── Name.md                  # Named task files — no date prefix (active until complete)
├── Projects/[name]/              # SMTM v5.4 Simple/Complex project structure
│   ├── ROADMAP.md                # project TOC: flat task list or phase hierarchy
│   ├── STATUS.md                 # state-only: Current Phase block + checkboxes (AI reads first)
│   ├── NEXT-STEPS.md             # active Claude/Talbot conversation; phase-scoped
│   ├── LESSONS.md                # process decisions, patterns, significant pivots
│   ├── UPGRADES.md               # ideas discovered during dev (not committed to phases)
│   ├── SPEC.md / PLAN.md         # optional: requirements / approach (stay current)
│   ├── logs/                     # YYYY-MM-DD_Description.md (dated session logs)
│   └── archive/                  # completed reference documents
└── Research/[topic]/

Full structure detail (Simple vs. Complex, phases/, DESIGN.md for dev projects): SMTM_System.md → Project Structure.

Session Start (MANDATORY)

1. Read Tasks/_tmp.md
2. If working on a project: read Projects/[name]/STATUS.md (state), then NEXT-STEPS.md (latest Talbot Response — the only feedback channel)
3. Act on the latest Talbot Response in NEXT-STEPS.md before proceeding

Task Lifecycle

Quick task (no log needed): Add checkbox to Tasks/_tmp.md — tick when done, fill in Claude Response section, never delete history.

Substantive task (needs context across sessions):

• Create Tasks/Task-Name.md from Tasks-Template.md (no date prefix)
• Single file for entire lifecycle — append Claude Response / Talbot Response to END, never delete history
• AI always appends ## Talbot Response + --- after its section
• Use /task-continue [filename] to continue; /task-complete [filename] to close

Project Lifecycle

Session end:

1. Tick completed checkboxes in STATUS.md (state only — no feedback/decisions there), update Last Updated date
2. Append Claude Response to Projects/[name]/NEXT-STEPS.md with Next Steps for Talbot
3. Write log if the session closed a phase: Projects/[name]/logs/YYYY-MM-DD_Description.md
4. Update Tasks/_tmp.md

Phase boundary: run /project-task-complete at every phase end (not just end-of-session) — it archives NEXT-STEPS.md to logs/ and resets it to the phase-start template, updates STATUS.md’s Current Phase block, and syncs ROADMAP.md.

Log Naming

YYYY-MM-DD_Description.md — no TYPE prefix on completed logs.

Git Commits (MANDATORY)

After any session that adds or modifies KB content, suggest a git commit. Do not wait for the user to ask. Automatically propose the commit with a meaningful message covering what changed. The KB repo is /mnt/d/FSS/KB/MBR/.

---

Lessons

Favicon generation: adding a new brand to generate-favicon.mjs

Three places need updating when adding a brand to scripts/generate-favicon.mjs:

1. Logo filename branch (logoFileName conditional)
2. Glyph-hiding block — SD hides char-dollar, MBR hides char-bar; match the element ID to the brand’s SVG structure
3. brandNames map for the site.webmanifest
4. The brand allowlist in main() (if (!['sd', 'ts', 'mbr'].includes(brand)))

The neutral-color mapping (black→primary, gray→secondary) is a no-op for brands with actual colors already in the SVG — the script still works correctly without any special-casing.

SVG favicon verification: inline SVGs only in Playwright

img src="file:///..." does not work in Playwright’s headless browser (page.setContent). To verify SVG rendering at multiple sizes, read the SVG files with fs.readFileSync and embed them directly as inline SVG in the HTML string. Use a sized() helper that replaces width="N" height="N" in the SVG tag to render at different display sizes.

Task file naming: no date prefix

SMTM task files use Name.md format — never YYYY-MM-DD_Name.md. Dates belong in log files and project logs, not task files. Task files are active work; their creation date is captured in frontmatter or git history.

CSS keyframe animation: set explicit initial state in CSS

When using @keyframes for logo/UI animations, the element’s state before the animation fires depends on the browser. Always set explicit CSS properties (e.g. opacity: 1 or opacity: 0) on the element itself — don’t rely solely on the 0% keyframe value. This prevents a flash-of-wrong-state on page load before the animation initialises. This is especially relevant for stacked elements (e.g. grid-area: 1/1) where the initial visibility must be correct before the first keyframe fires.

Design exploration → two artifacts

Multi-session design tasks (logo iterations, UX explorations) should produce:

1. Lean decision log in the owning dept’s Logs/YYYY-MM-DD_Description.md (dept-routed per SMTM v5.4; 09_Logs/ retired 2026-07-09) — what was decided and why
2. Full task file moved to _WorkingOn/Brainstorming/archive/YYYY-MM-DD_TaskName.md — full iteration history as design audit trail

The relevant spec doc (e.g., Brand.md) canonizes the final outcome. Never delete the iteration history — a single session’s reasoning can resolve future ambiguity about why a decision was made.

CSS overlay positioning on text glyphs: use transform, not bottom

When positioning a CSS element (e.g., a ::after bar) relative to a font glyph, bottom/top/height CSS properties snap to integer pixels. This snapping is non-monotonic — at different font sizes the snap error changes direction (e.g., bottom: 0.06em at 1.25rem = 1.2px snaps DOWN 17%, but at 2rem = 1.92px snaps UP 4%). No single bottom value is correct at all sizes; tuning against one size breaks another. Fix: anchor the overlay with transform: translate() — GPU-rendered in floating-point, no pixel snap.

Derivation pattern: original bottom: Xem; height: Hem → equivalent transform: top: 0; height: Hem; transform: translateY(1em - X - H).

CSS positioning diagnostic: build a multi-size grid before tuning values

When a CSS positioning value works at one font-size/zoom but fails at others, stop tuning and diagnose. Build a diagnostic HTML page showing: all relevant font-sizes × weights × zoom levels, with hairline rulers marking the ground-truth metric positions (x-height top/middle, baseline). Take one screenshot per zoom level. The misalignment pattern across the grid identifies the root cause:

• Non-monotonic drift (too low here, too high there) → pixel snap on layout properties → use transform
• Zoom-dependent shift (fine at 100%, wrong at 125%) → font hinting → use geometricPrecision
• Context-only failure (fine in isolation, wrong in card heading) → inherited styles from parent (line-height, font-weight) → inspect the specific context’s CSS

Without the grid, value-tuning loops can run indefinitely because you’re calibrating against a moving target at a single test point.

Font hinting causes glyph position drift across zoom levels

When overlaying a CSS element on a font glyph (e.g., a bar through an s), font hinting re-positions the glyph within the em-box at different browser zoom levels (100% vs 125% vs 150%). The CSS overlay is math-stable; the glyph moves. Result: bar appears in different relative positions at each zoom — no CSS positioning value can track this. Fix: add text-rendering: geometricPrecision; font-optical-sizing: none to the target character only (not the whole component). This disables hinting for that glyph so it renders at its math x-height regardless of zoom, aligning with the math-positioned CSS overlay.

Trade-off: the un-hinted character may look slightly fuzzier at very small sizes (12–14px), but Inter renders cleanly enough that this is imperceptible in practice.

---

Closing Communication (MANDATORY)

After any task that produces a log or task file, the final message must include both paths:

📄 Task/log file:
  WSL:     /mnt/d/FSS/KB/MBR/_WorkingOn/...
  Windows: D:\FSS\KB\MBR\_WorkingOn\...

Skills

Skill	What it does
/task-start [file]	First session on a task: read, execute, append first Claude Response
/task-continue [file]	Process latest Talbot Response in task file, append Claude Response
/task-prep [file]	Hydrate a task file with context before execution (any model can pick it up)
/task-complete [file]	Close task: LESSONS.md candidates, purge, log/delete, auto-commit
/project-start [name]	Create a new project folder (ROADMAP/STATUS/NEXT-STEPS + optional SPEC/PLAN)
/project-continue [name]	Pick up a project session: read STATUS.md + NEXT-STEPS.md, act on latest Talbot Response
/project-task-complete [name]	Phase-boundary close: archive NEXT-STEPS.md, reset template, sync STATUS/ROADMAP, log, auto-commit