From 6ac937b49da72956780fd65a720dd9952fc2ffd9 Mon Sep 17 00:00:00 2001 From: jdalton Date: Tue, 31 Mar 2026 23:00:03 -0400 Subject: [PATCH 1/2] chore: update CLAUDE.md with agent protocols --- CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 44 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c91c27a7b..c16857733 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,10 +2,6 @@ **MANDATORY**: Act as principal-level engineer. Follow these guidelines exactly. -## CANONICAL REFERENCE - -This is a reference to shared Socket standards. See `../socket-registry/CLAUDE.md` for canonical source. - ## 👤 USER CONTEXT - **Identify users by git credentials**: Extract name from git commit author, GitHub account, or context @@ -19,14 +15,53 @@ This is a reference to shared Socket standards. See `../socket-registry/CLAUDE.m **MANDATORY**: Review CLAUDE.md before any action. No exceptions. +- Before ANY structural refactor on a file >300 LOC: remove dead code, unused exports, unused imports first — commit that cleanup separately before the real work +- Multi-file changes: break into phases (≤5 files each), verify each phase before the next +- When pointed to existing code as a reference: study it before building — working code is a better spec than any description +- Work from raw error data, not theories — if a bug report has no error output, ask for it +- On "yes", "do it", or "go": execute immediately, no plan recap + ## VERIFICATION PROTOCOL **MANDATORY**: Before claiming any task is complete: -1. Test the solution end-to-end -2. Verify all changes work as expected -3. Run the actual commands to confirm functionality -4. Never claim "Done" without verification +1. Run the actual command — execute the script, run the test, check the output +2. State what you verified, not just "looks good" +3. **FORBIDDEN**: Claiming "Done" when any test output shows failures, or characterizing incomplete/broken work as complete +4. If type-check or lint is configured, run it and fix ALL errors before reporting done +5. Re-read every file modified; confirm nothing references something that no longer exists + +## CONTEXT & EDIT SAFETY + +- After 10+ messages: re-read any file before editing it — do not trust remembered contents +- Read files >500 LOC in chunks using offset/limit; never assume one read captured the whole file +- Before every edit: re-read the file. After every edit: re-read to confirm the change applied correctly +- When renaming anything, search separately for: direct calls, type references, string literals, dynamic imports, re-exports, test files — one grep is not enough +- Never fix a display/rendering problem by duplicating state — one source of truth, everything reads from it + +## JUDGMENT PROTOCOL + +- If the user's request is based on a misconception, say so before executing +- If you spot a bug adjacent to what was asked, flag it: "I also noticed X — want me to fix it?" +- You are a collaborator, not just an executor + +## SCOPE PROTOCOL + +- Do not add features, refactor, or make improvements beyond what was asked — band-aids when asked for band-aids +- Try the simplest approach first; if architecture is actually flawed, flag it and wait for approval before restructuring +- When asked to "make a plan," output only the plan — no code until given the go-ahead + +## SELF-EVALUATION + +- Before calling anything done: present two views — what a perfectionist would reject vs. what a pragmatist would ship — let the user decide +- After fixing a bug: explain why it happened and what category of bug it represents +- If a fix doesn't work after two attempts: stop, re-read the relevant section top-down, state where the mental model was wrong, propose something fundamentally different +- If asked to "step back" or "we're going in circles": drop everything, rethink from scratch + +## HOUSEKEEPING + +- Before risky changes: offer to checkpoint — "want me to commit before this?" +- If a file is getting unwieldy (>400 LOC): flag it — "this is big enough to cause pain — want me to split it?" ## Critical Rules @@ -378,6 +413,7 @@ Socket CLI integrates with various third-party tools and services: - **Array destructuring**: Use object notation `{ 0: key, 1: data }` instead of array destructuring `[key, data]` - **Dynamic imports**: 🚨 FORBIDDEN - Never use dynamic imports (`await import()`). Always use static imports at the top of the file - **Sorting**: 🚨 MANDATORY - Always sort lists, exports, and items in documentation headers alphabetically/alphanumerically for consistency +- **Comment policy**: Default to NO comments. Only add one when the WHY is non-obvious to a senior engineer reading the code cold - **Comment placement**: Place comments on their own line, not to the right of code - **Comment formatting**: Use fewer hyphens/dashes and prefer commas, colons, or semicolons for better readability - **Await in loops**: When using `await` inside for-loops, sequential processing is acceptable when iterations depend on each other From 40aa7b46e274739f672ee5fff719979eaf047a32 Mon Sep 17 00:00:00 2001 From: jdalton Date: Wed, 1 Apr 2026 10:13:30 -0400 Subject: [PATCH 2/2] chore: add agent protocol sections to CLAUDE.md --- CLAUDE.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index c91c27a7b..63a98d39c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -424,6 +424,29 @@ Socket CLI integrates with various third-party tools and services: - **Formatting**: Uses Oxfmt for code formatting with 2-space indentation - **Line length**: Target 80 character line width where practical +### Completion Protocol +- **NEVER claim done with something 80% complete** — finish 100% before reporting +- When a multi-step change doesn't immediately show gains, commit and keep iterating — don't revert +- If one approach fails, fix forward: analyze why, adjust, rebuild, re-measure — not `git checkout` +- After EVERY code change: build, test, verify, commit. This is a single atomic unit +- Reverting is a last resort after exhausting forward fixes — and requires explicit user approval + +### File System as State +The file system is working memory. Use it actively: +- Write intermediate results and analysis to files in `.claude/` +- Use `.claude/` for plans, status tracking, and cross-session context +- When debugging, save logs and outputs to files for reproducible verification +- Don't hold large analysis in context — write it down, reference it later + +### Self-Improvement +- After ANY correction from the user: log the pattern to memory so the same mistake is never repeated +- Convert mistakes into strict rules — don't just note them, enforce them +- After fixing a bug: explain why it happened and whether anything prevents that category of bug in the future + +### Context Awareness +- Tool results over 50K characters are silently truncated — if search returns suspiciously few results, narrow scope and re-run +- For tasks touching >5 files: use sub-agents with worktree isolation to prevent context decay + --- ## Quality Standards