capture

What is a blindspot

1. A blindspot is a default agentic tendency that produces a bad output in a specific context, absent intervention. Cognitive biases, but for coding agents.
2. Code anti-patterns are not blindspots; the blindspot is the agent's tendency to produce them.
3. Style preferences are not blindspots.
4. One-off bugs are not blindspots.
5. Anything specific to a single codebase or task is not a blindspot.

Record schema

1. name: short noun phrase. The human label. Filename slug is derived from this.
2. categories: closed set. One or more of: code, planning, review, debugging, communication.
3. tags: freeform keywords. Lowercase, single token preferred.
4. applies_when: freeform contextual triggers. Each entry is a short phrase.
5. user_intervention_required: boolean. true if a consumer agent must surface the blindspot and get explicit user direction before proceeding; false if the consumer agent applies the mitigation silently.
6. Body has three required sections in order: Behavior, Signal, Mitigation.
7. Behavior: one paragraph. Descriptive, third-person, present tense. "Agent does X when Y." Never prescriptive.
8. Signal: what is observed after the fact that tells you the tendency fired.
9. Mitigation: the counter-instruction phrased as the actual prompt to give.

Language conventions

1. name is a noun phrase ("anchoring on first solution"). Never an imperative ("don't anchor", "avoid anchoring").
2. Behavior is descriptive ("Agent rewrites working code when asked to add a feature"). Never prescriptive ("Don't rewrite working code").
3. Mitigation is the counter-prompt as you would say it to the agent.
4. Reject imperative names and imperative Behavior phrasings during the interview. Do not write the record until phrasing complies.

High-quality rubric

1. Generalizable. The tendency must apply across tasks and codebases, not to one specific situation.
2. Default. The agent does this without being asked. Behavior that only happens under specific prompting is not a blindspot.
3. Mitigable. There is a counter-instruction that prevents or replaces the tendency.
4. Observable. The Signal is concrete enough that a reviewer can spot when the tendency fired.
5. If a candidate fails any of these tests, tell the user and stop. Do not write a low-quality record.

Examples in records

1. Zero by default. One allowed if the abstract phrasing genuinely does not land. Never two. No attachments.

Procedure

1. Determine the active mode from the invocation:
   • If --diff was passed or the invocation included a diff, the mode is diff.
   • If --last-message was passed or the invocation pointed at a prior assistant message, the mode is last-message.
   • If free text describing the blindspot was passed, the mode is free-text.
   • If nothing was passed, the mode is no-input.
2. Read the matching reference file and follow it to collect candidate values: ${CLAUDE_SKILL_DIR}/references/diff-mode.md, ${CLAUDE_SKILL_DIR}/references/last-message-mode.md, ${CLAUDE_SKILL_DIR}/references/free-text-mode.md, or ${CLAUDE_SKILL_DIR}/references/no-input-mode.md.
3. Derive a candidate slug from the user's rough name using lowercase, hyphenated, alphanumeric-only.
4. List existing slugs: ls ${BLINDSPOTS_HOME:-$HOME/.blindspots}/records/. If a returned filename equals the candidate slug or a near-duplicate, tell the user and offer /blindspots:update on that slug instead. Stop unless the user explicitly confirms creating a new record.
5. Run the mode-specific interview to collect every required field. Enforce the language conventions and high-quality rubric during the interview. Do not accept imperative phrasing.
6. Show the user every collected value and ask for confirmation before writing.
7. Read the template at ${CLAUDE_SKILL_DIR}/templates/blindspot.md.template. Substitute every placeholder with the confirmed values. For list-valued fields (categories, tags, applies_when), repeat the - <item> line once per entry under the matching key. For user_intervention_required, substitute exactly true or false.
8. Write the substituted record to ${BLINDSPOTS_HOME:-$HOME/.blindspots}/records/<slug>.md via the Write tool. The PostToolUse hook rebuilds index.json and tags.json.
9. Tell the user the record was written and print the absolute path. claude --plugin-dir /Users/brenna/Documents/personal/ai-stuff/utilitry/plugins/permitcrab