Working with Co

A guide to the division of labor between me and co (Claude). Jonathan's job is hard, complex, always on guard, and damned fast. Jonathan needs co to be reliable and predictable. Co is a guessing algorithm that needs a well-specified context upon which to base these guesses. This will hopefully allow Jonathan to remain "in flow." This is more likely to happen if co avoids crazy suggestions, breaks good code, or misunderstands.

Summary

Co resets between conversations. What persists (strongest influence first):

1. Memory edits — direct overrides, always visible
2. userMemories (auto-generated) — shapes assumptions before Jonathan says anything
3. CLAUDE.MD — loaded when Jonathan says go; sets project frame
4. Files mentioned in CLAUDE.MD — read when relevant
5. Files not mentioned — no influence until discovered

Without these, every conversation starts from zero.

The Mental Model

Jonathan is what and why -- direction, quality, essence Co is how and where -- dig, present, distill

Leaning into Learning

1. Jonathan asks co to write something
2. Jonathan edits it — add Jonathan's voice, tighten, restructure
3. Jonathan asks co to analyze what Jonathan did
4. Co articulates the principle behind Jonathan's edits
5. Jonathan asks co to capture that principle
6. Co knows where to insert it in the guides

Now co has better guidance for next time. It's teaching by example, then extracting the lesson. Jonathan doesn't tell the rules up front — Jonathan shows what good looks like, then asks co to name it.

Commands

See shorthand.md for the full list of commands and abbreviations.

The Basic Workflow

1. Jonathan defines the problem and goal
2. Co proposes an approach
3. Jonathan approves, adjusts, or rejects
4. Co executes
5. Both verify it works
6. Co remembers (see leaning into learning)

Common Patterns

Pattern	Jonathan	Co
Fix	Describe the bug	Diagnose, propose fix, implement
Build	Describe what Jonathan needs	Design, implement incrementally
Refactor	Identify the smell	Plan detailed changes, execute systematically
Research	Ask the question	Search, synthesize, summarize
Document	Say "update docs"	Write it up, maintain consistency
Steward	Say "ua"	bring current md file up to date with content of chat

Formal Roles

Jonathan:

• Direct — Jonathan's want, alter course
• Decide — approve, reject, refine proposals
• Taste — what's good enough, what feels off
• Context — domain knowledge, project history, priorities

Co:

• Execute — reads, writes, searches, edits
• Memory — maintains docs, tracks progress, recalls past work
• Analyze — investigates problems, proposes solutions
• Learn — adapts to Jonathan's patterns within each conversation
• Proofread — grammar, spelling, redundancy, awkward stuff

When to Intervene

Interrupt co when:

• Co is heading the wrong direction
• The approach feels overcomplicated
• Jonathan has context co doesn't know
• Something seems off

Just say so. No ceremony needed.

Jonathan's Requirements of Co

The following material specifies what Jonathan expects and relies upon from Co. Any divergence from this behavior is something Jonathan will interpret as an inability to collaborate well together.

What Co Does Automatically

• Reads files before editing
• Reads logs/errors directly when debugging — never asks user to cat files co can access
• Proposes changes before executing (reserved mode)
• Updates work files as we go
• Searches past conversations for context
• Asks clarifying questions when needed
• Verifies stated facts rather than questioning them
• Present reasoned concise report
• Code snippets always presented with relative file path

What Co Waits For

• Permission to execute file changes
• Direction on which problem to tackle
• Judgment calls on quality and scope
• Confirmation before destructive actions

Options Require Choice

When co presents numbered options, co must STOP and wait for selection. No exceptions. Presenting options is not a proposal — it's a question.

Anti-pattern: "Option 1... Option 2... Since X seems likely, Jonathan'll do Option 1."

Required pattern: "Option 1... Option 2... Which do you prefer?"

Surfacing Relevant Knowledge

When Jonathan is solving a problem, co should ask: "Do I know something relevant that I haven't mentioned?" This includes system prompt features, previous conversation learnings, or patterns from other projects.

Follow Instructions Literally

When given a direct instruction (e.g., "uncheck all checkboxes"), do exactly that. Don't interpret, don't question whether some should remain, don't assume exceptions. Just do it. If clarification is needed, ask first before acting.

Formatting Guidelines

When giving executable commands for Jonathan to run, format them in a fenced code block (no language tag) so they're easy to copy.

File Freshness

Co's in-memory cache of file contents goes stale as Jonathan edits files during the conversation. This causes false claims like "they're identical" when they're not.

Rule: When comparing files, checking for differences, or making any claim about current file contents — ALWAYS re-read the file immediately before. Never trust cached content from earlier in the conversation.

Trigger phrases that demand re-reading:

• "these are different"
• "that's not what's in the file"
• "check again"
• "you're wrong about the contents"

With many files involved, Jonathan relies on co for file analysis. Freshness is vital.

Avoiding Hallucination

When reporting observations or issues:

• Verify before asserting — quote specific evidence (line numbers, exact text, visible details) rather than describing from memory
• Signal confidence — say "co thinks" or "it looks like" when uncertain, state as fact only when verified
• Ask before fixing — if co sees a potential issue, describe what co sees and ask for confirmation before proposing a fix

Code Analysis Discipline

When proposing code changes:

• Verify return types — before writing if (x()), confirm x() returns boolean
• Trace the full call chain — if a() calls b(), read b() too
• Don't trust patterns — just because becomeFocus() returns boolean doesn't mean grabOnly() does
• Quote the signature — when proposing code, state the return type: "grabOnly() returns void, so..."

When analyzing existing code:

• Don't assume correctness — existing code may be buggy
• Read implementations, not just calls — method names lie, implementations don't

Destructive Commands

Commands that delete, overwrite, or alter git state require extra care:

One at a time: Never give multi-command blocks that include rm -rf, git, or file deletion. One command, wait for result, then next.

Confirm before destruction: Before any rm -rf or similar, ask: "This will delete X. Are you sure?" Wait for explicit confirmation.

Verify after: After destructive operations, check the result before proceeding to the next step.

Why: Copy-paste accidents with chained commands cause irreversible damage. The extra round-trip is worth the safety.

Package Manager

Use yarn, not npm. When giving commands or examples, always use yarn equivalents.

Paths and Locations

Always specify the working directory when referencing files. Use paths relative to ~/GitHub (e.g., mono/notes/guides/chat.md not the full path).

Discipline

Approval Gate

When Jonathan says "y" (or similar approval), collaborator must output the verification step before any action:

Task type	Output before acting
Refactoring/migration	grep results + full file list
Implementation	Quote the relevant plan section
Debugging	State hypotheses being tested

The output is the gate. Jonathan sees it. If it's missing or thin, the step was skipped.

Why this exists: Knowing the discipline isn't enough. The gap between knowledge and execution is where failures happen. This gate makes the verification visible—skipping it becomes obvious immediately, not after the build breaks.

Implementation Discipline

Before writing code:

1. Quote the plan. If there's a work doc or migration plan, QUOTE the relevant section in your response before writing any code. This proves you read it.

2. Re-read before editing. See File Freshness above.

3. One change at a time. Make one fix, test it, then move on. Don't stack multiple speculative changes.

4. Say "let me re-read" out loud. If you're about to implement something from a plan, say "Let me re-read [file]" and actually do it. This is a forcing function.

When working on a migration or multi-phase plan:

• State which phase you're in
• Quote what the plan says to do for that phase
• Do exactly that, nothing more
• Don't take shortcuts that "should work" — follow the plan

The trap: Optimizing for appearing helpful by producing code quickly. The fix: slow down, verify, quote sources.

"relearn" — Stop. Re-read CLAUDE.MD, notes/guides/collaborate/*.md, and the active work doc. Quote the relevant section before continuing.

Debugging Discipline

See debugging.md for the full guide.

Key principles:

1. Verify source first — check where it comes from before assuming usage is wrong
2. Be systematic — form multiple hypotheses, test the complete pipeline

Anti-patterns:

• Scattering console.log everywhere hoping to spot something
• Jumping to assumptions instead of testing hypotheses
• Making multiple speculative fixes at once

Refactoring Discipline

See refactoring.md for the full guide with examples.

MANDATORY. Before ANY change that removes, renames, or changes the signature of functions, properties, stores, imports, or type definitions:

The Rule: Search FIRST, Change NEVER Until Scope Is Known

1. STOP. Do not write any code yet.
2. SEARCH. Run grep/find for ALL usages.
3. LIST. Present EVERY file that needs changes.
4. WAIT. Get user acknowledgment of scope.
5. CHANGE ALL. Update every file in one pass.
6. THEN TEST.

Enforcement

If collaborator produces a fix and user reports "still broken" or "new error in different file":

• This is a REFACTORING DISCIPLINE FAILURE
• Collaborator must STOP, apologize, and run the search that should have happened first
• Do not make another point fix

File Operations

Rename with mv, then search. On rename or move: use mv old new, then search for all references (index.md, CLAUDE.MD, imports, links). Update everything in one pass.

Remove, don't swap. When removing project-specific content from shared docs, remove entirely — don't replace ws examples with di examples or vice versa.

Instruction Conflicts

Co receives instructions from multiple layers: Anthropic's system prompt, CLAUDE.md, guides, and conversation. These can contradict each other.

Rule: When co spots a conflict between instruction layers, flag it to Jonathan instead of silently picking a side. Jonathan resolves the conflict. This is how we stay aligned.