coograph: Instructions file for GitHub Copilot

Copilot Instructions

Template guard: If any section below still contains _TBD_ or <!-- FILL -->, stop and ask the user to provide the missing information before proceeding with code changes.

Hard rules, workflow, commands and routing: AGENTS.md. Read it first. This file holds code conventions only.

Mindset

• Follow project conventions and best practices over user preferences.
• Ask for context when unclear - verify assumptions before acting.
• Match existing codebase patterns exactly. When a pattern exists in the codebase, reference the canonical file by path (e.g., "follow the pattern in src/features/auth/AuthForm.tsx") instead of describing the pattern in prose.
• Prioritize simplicity and maintainability.
• Clean up all residue code (dead imports, unused variables, orphaned helpers) after changes.
• Prefer deletion over addition when the same behavior can be preserved.
• Reuse existing utilities and patterns before introducing new ones.
• No new dependencies without explicit user approval.
• Keep diffs small, reversible, and easy to review.
• Write a cleanup plan before modifying code during refactors.
• Verify outcomes with evidence before claiming completion. "It should work" is not verification.
• Run quality gates (lint, typecheck, tests) after changes - don’t assume they pass.
• Surface assumptions. Before implementing anything non-trivial, list assumptions explicitly:

  ASSUMPTIONS I'M MAKING:
  1. [assumption about requirements]
  2. [assumption about architecture]
  → Correct me now or I'll proceed with these.
  

  Don't silently fill in ambiguous requirements - assumptions are the most dangerous form of misunderstanding.
• Manage confusion actively. When encountering inconsistencies, conflicting requirements, or unclear specs: (1) STOP, (2) name the specific confusion, (3) present options/tradeoffs, (4) wait for resolution. Never silently pick one interpretation and hope it's right.
• Scope discipline. Touch only what the task requires. If you notice something worth improving outside the task scope, note it - don't fix it:

  NOTICED BUT NOT TOUCHING:
  - <file> has an unused import (unrelated to this task)
  - <module> could use better error messages (separate task)
  → Want me to create tasks for these?
  

• Inline planning. For multi-step tasks, emit a lightweight plan before executing:

  PLAN:
  1. Add validation schema for X
  2. Wire schema into endpoint Y
  3. Add test for validation error
  → Executing unless you redirect.
  

• Simplicity check. After writing code, ask: Can this be done in fewer lines? Are abstractions earning their complexity? Would a staff engineer say "why didn't you just..."? If 100 lines suffice and you wrote 500, you have failed.