marcus: Instructions file for Claude Code

General Guidelines:

• When writing commit messages, NEVER auto-add your agent name as co-author
• When writing or substantially editing Markdown files, put each full sentence on its own line. Preserve normal Markdown structure, but avoid wrapping multiple sentences onto one physical line
• When making technical decisions, do not give much weight to development costs. Instead, prefer quality, simplicity, robustness, scalability, and long term maintainability.
• When doing bug fixes, always start with reproducing the bug in an E2E setting as closely aligned with how an end user might experience it. This makes sure you find the real problem so your fix will actually solve it.
• When end-to-end testing a product, be picky about the UI you see and be obsessed with pixel perfection. If something clearly looks off, even if it is not directly related to what you are doing, try to get it fixed along with the other stuff.
• Apply that same high standard to engineering excellence: lint, test failures, and test flakiness. If you see one, even if it is not caused by what you are working on aright now, still get it fixed.

SESSION_START:

• At session start, read ~/.simon/memory-bank/activeContext.md for current focus and recent state.
• Also read ~/.simon/memory-bank/progress.md for what shipped / what's left / critical reminders.
• Optionally read the other four files in ~/.simon/memory-bank/ (projectbrief, productContext, techContext, systemPatterns) when you need project-wide context — they change rarely.
• When the user says "update simon memory bank", review the recent conversation and rewrite activeContext.md + progress.md to match the new state. Leave the other four files alone unless the stack or patterns actually changed.

SIMON_DECISION_LOGGING: Automatically capture decisions, blockers, and concerns to Simon as we work on Marcus. Use the simon CLI via Bash tool. No need to ask permission for routine logging — just do it at the moment a decision/blocker/concern surfaces. Full automation guidelines: ~/.claude/skills/simon/SKILL.md

WHAT TO LOG:

• DECISION: significant architectural choices with rationale + alternatives simon log decision "what we chose" --rationale "why" --alternatives "A,B,C" --project marcus [--issue N]
• BLOCKER: external dependencies or critical uncertainties stopping progress simon log blocker "what is blocked" --by "what blocks it" --needs "what unblocks" --project marcus
• THOUGHT: risks, observations, concerns (not full blockers) simon log thought "concern text" --project marcus --urgency high|medium|low [--issue N]
• IMPETUS: major driving forces or deadlines that shape priorities simon log impetus "name" --date YYYY-MM-DD --description "..." --drives "task1,task2"

WHEN TO LOG:

• At the moment of decision, not at session end (capture in-the-moment reasoning)
• When user says "let's go with X" or "we should do Y instead of Z" — that's a decision
• When user identifies a blocker or you discover one during work — that's a blocker
• When risks or concerns surface during analysis — that's a thought
• When a deadline, funding milestone, or strategic commitment is mentioned that shapes priorities across many decisions — that's an impetus (broader scope than a decision; an impetus drives multiple decisions)
• Don't log routine Q&A, code edits, or obvious choices — only architecturally significant moments

EDITING / BACKFILLING ENTRIES:

• simon edit <id> --issue N — set or update issue number on an existing entry
• simon edit <id> --add-tag X — add a tag (preserves existing tags)
• simon edit <id> --drives "1,2,3" — replace drives list on an impetus
• simon edit <id> --description "..." — update description
• Also: --urgency, --complexity, --project, --due, --status, --reason
• Use this to backfill issue numbers on old entries that mention #NNN in text but lack the issue field, so simon find --issue N queries work