What should your agent know about your codebase before it touches anything?

[troyjr4103]

I'll start. Before an agent changes a function in my code I want it to know the callers, which of those are tests, and what kind of reference each one is. What's on your list? I'm collecting these to decide what Kin should answer first.

[wellkilo]

For an agent, I would make the pre-edit answer change-specific, not a generic repository summary. The smallest useful evidence bundle for a symbol is:

1. Identity and contract

   • canonical symbol ID, file/span, language
   • full signature and exported visibility
   • type constraints, documented invariants, and error contract

2. Inbound impact

   • direct callers, grouped as production / test / generated / example
   • reference kind: call, import, type use, construction, override, callback registration, string/config reference
   • confidence and provenance for every edge

3. Outbound obligations

   • functions/types/resources the symbol depends on
   • side effects: filesystem, network, database, process, global state
   • transaction, concurrency, retry, cancellation, and ownership boundaries

4. Behavioral evidence

   • tests that directly exercise the symbol
   • tests that reach it transitively
   • fixtures/snapshots/golden files tied to it
   • the narrowest command that verifies the affected path

5. Change context

   • recent commits that changed the symbol or its contract
   • open issues/PRs touching the same area
   • code owners or reviewers for the path
   • generated-code/source-of-truth relationship

The important part is distinguishing known absence from missing coverage. “No callers found” should include which languages, reference kinds, revisions, generated files, dynamic dispatch, macros/reflection, and uncommitted changes were or were not indexed. Otherwise an empty result becomes false confidence.

I would expose this in layers rather than one huge response:

impact <symbol> --depth 1
  -> direct callers + reference kinds + tests

trace <symbol>
  -> local contract + dependencies + side effects

verify <symbol>
  -> targeted tests/checks + coverage gaps

history <symbol>
  -> contract-changing commits + active work

For a first implementation, my priority would be:

• precise symbol resolution;
• typed inbound references;
• production-vs-test classification;
• implementation/override relationships;
• generated-file and dynamic-edge warnings;
• targeted verification commands.

That set prevents the most common bad edit: changing a locally simple function whose real contract lives in an interface, a callback registry, a serializer/schema, or a test fixture elsewhere.

One product detail I would preserve from Kin's current README is the explicit “coverage is incomplete” boundary. Every answer should carry its evidence scope and index revision, so an agent knows whether it is looking at a proof, a strong signal, or only a partial map.

If this is useful for prioritizing Kin's first query surfaces, please mark it as the accepted answer.

[troyjr4103]

Thanks for laying this out. Starting with the specific change makes sense, and the distinction between no callers and missing coverage is one I want to keep explicit. The interface and callback examples are useful because a simple-looking function can have obligations elsewhere.

Do you have a small public example where one of those connections was missed? I'd like to have a concrete case to check against Kin's current output. This list is useful feedback, but I don't want to imply Kin already reports everything in it.