Philosophy

insrc exists to make AI-assisted engineering on large, long-lived codebases grounded, structured and traceable — the opposite of ad-hoc grep → guess → patch. An assistant is only as good as its model of your code and the discipline around the changes it makes. insrc supplies both: a citation-grounded index of the codebase, and a tracked workflow that leaves an auditable trail from the first ask to the merged change.

The failure mode we designed against

On a small project an assistant can hold the whole thing in context and mostly get away with improvising. On a large or old codebase that breaks down, and the failures compound:

• Hallucinated structure. Paths, symbols and call relationships get invented because they were never looked up.
• Ungrounded assumptions. A change is made against how the code is imagined to work, not how it actually does.
• Untracked, undocumented edits. One-off patches land with no statement of intent, no design, and no record of the alternatives that were rejected.
• Lost rationale. Six months later nobody — human or model — can reconstruct why the code is shaped the way it is.

Speed without structure produces drift. insrc trades a little ceremony for correctness and a durable trail — because on a system that has to live for years, that is the cheaper trade.

Grounding over guessing

Understanding comes first. insrc parses your repositories into a typed entity/relation graph plus a vector index, and every answer is built from that store rather than from a blind file read:

• Every claim is cited. The analyze framework returns a verified, 7-layer context bundle where each statement is anchored to a real exploration output — a module profile, a symbol locate, a class hierarchy, a doc constraint. File paths come from the index, so they cannot be hallucinated.
• Structure is queried, not skimmed. Callers, callees, transitive closures and unreachable code are answered from the graph; semantic questions go through vector search. No raw file dumps — context is always structured entity summaries and relations.
• Scope is bounded. Searches span only the transitive dependency closure of the active repo, so a query stays anchored to what actually matters to it.

Structure scales; improvisation doesn't

The core guarantee is simple: every change, big or small, is tracked. A natural-language ask is sized and routed by triage, then flows through an authoring pipeline that maps 1:1 to the software-engineering ladder every team already knows — Epic → Story → Task:

• Right-sized, never skipped. Triage routes an epic through the full chain, a feature through a standalone design → plan → build, a trivial change straight to build — but nothing bypasses the ledger. Even a one-liner becomes a record.
• Human-gated between every stage. Each stage produces exactly one artifact and hard-refuses to start until the upstream artifact is approved. The model never decides to jump ahead on its own.
• Decisions are made once, upstream. Open questions are resolved at the design stages and carried forward, so the plan and the build inherit settled decisions instead of re-litigating them.

The payoff is that a large effort decomposes into reviewable slices with explicit boundaries — the same reason teams break work into epics and stories in the first place, now enforced for the assistant too.

Traceability & compliance

Because each stage writes a persistent, cited artifact, the chain is the audit trail. From any merged change you can walk backward to the plan that produced it, the design that shaped it, the definition that framed it, and the review that gated it — each one a file that outlives the session:

• Two sets of eyes. Design and code are reviewed by an independent pass before approval — a different reviewer than the author — with block verdicts that withhold completion until resolved.
• Tracker-native. Approved artifacts push to a GitHub Epic ▸ Story ▸ Task tree as real sub-issues, linking each design/plan blob back from its issue, so the trail lives where your team already works.
• Reversible by construction. Every write insrc makes into a host-owned config or rules file is marker-delimited and replace-only — it preserves your surrounding content and is fully reversed on uninstall. Nothing is silently mutated.
• Provenance, not just output. Because claims are cited and artifacts are versioned, "why is this here?" has a real answer — the raw material compliance, onboarding and post-incident reviews all depend on.

Documentation that can't drift

Hand-written docs rot the moment the code moves. insrc closes the gap from both ends:

• Docs generated from the live graph. insrc_docgen produces self-contained, offline HTML documents — type/class structure, module-dependency maps, call sequences from an entry point, narrated walkthroughs — where every node and edge is graph-derived, so no path or symbol is invented and the diagram tracks the real code.
• Design artifacts are living documentation. The HLD/LLD chain records the intent and the rationale next to the code, not in a wiki that goes stale — and the next workflow reads it as the authoritative source.
• Understanding on demand. Any teammate (or assistant) can ask a grounded question and get a cited answer instead of spelunking, which is documentation at the moment you need it.

Accuracy is the product

The principles below are non-negotiable — they are what the rest is built to protect:

Where next