Codebase Investigation

Use the smallest amount of context necessary while preserving correctness across the affected code path.

Before modifying unfamiliar or architecture-relevant code:

1. Locate and read the applicable AGENTS.md.

2. Locate architecture/design documentation relevant to the task.

3. Inspect only the relevant repository/module structure instead of reading the entire repository.

4. Prefer Serena semantic tools for code navigation:

   • inspect symbol overviews;
   • locate definitions;
   • locate references;
   • trace callers/callees;
   • inspect inheritance and implementations where relevant.

5. Use grep/text search only when semantic lookup is unsuitable or when searching for configuration keys, literals, comments, or dynamically referenced names.

6. Trace the concrete data and control flow affected by the requested change:

   • where each important value is produced;
   • how it is transformed;
   • which functions/modules consume it;
   • what outputs propagate downstream.

7. Identify affected:

   • interfaces and function signatures;
   • configuration and defaults;
   • callers and downstream users;
   • tests, evaluation scripts, demos, or other verification paths.

8. Before editing, internally verify cross-function contracts along the affected call chain, including where relevant:

   • tensor/array shapes and dimension ordering;
   • batch, time, channel, spatial, sequence, or feature dimensions;
   • argument names, ordering, defaults, and optional values;
   • return-value structure and unpacking;
   • dtype and precision;
   • device placement;
   • scalar vs tensor/array values;
   • mutable state and object attributes;
   • expected ranges, normalization, coordinate systems, or units.

9. Summarize the intended modification and affected data/control flow internally before editing.

10. Make the smallest coherent implementation change that preserves existing interfaces and assumptions unless the task explicitly requires changing them.

11. Verify the change using the strongest available method:

• first run the most relevant existing unit/integration tests;
• otherwise run an existing evaluation, demo, smoke-test, or sanity-check path;
• if no executable verification exists, statically trace the affected caller → callee chain and check parameter/return contracts end-to-end;
• explicitly verify shape/dimension propagation, argument compatibility, return-value usage, dtype/device consistency, and important state transitions;
• when practical and low-cost, execute the smallest relevant function/module with representative or synthetic inputs to catch runtime shape/signature errors.

12. If verification reveals an inconsistency, trace it back through definitions and references before applying further edits; do not patch downstream symptoms without understanding the upstream contract.

13. If architecture, public interfaces, assumptions, configuration semantics, or data flow changed, update the corresponding design documentation.

Do not bulk-read files or the entire repository when symbol-level retrieval is sufficient.

Do not assume code is correct merely because it is syntactically valid. Pay particular attention to cross-file interface mismatches and silent tensor-shape errors.

For third-party APIs or libraries whose current behavior matters, use Context7 rather than relying on model memory.