Skip to content

Brownfield survey

On an existing codebase the loop starts with one more step, the survey. The engine maps the code deterministically; agents write documentation backed by evidence; the result becomes the indexed context of every later step.

Status

This page describes the design of the survey. No part of it is built today. What comes next is in the roadmap.

Step Done by Output
Scan Engine Module tree, languages, entry points, dependencies, token count per file
Map Engine Symbols extracted with tree-sitter, import and call graph, ranking of central files, a map within a token budget
Documentation with evidence Agents, on top of the map Architecture, conventions, domain glossary, main flows; every claim cites file and line, and whatever cannot be shown goes into a section of unverified items
Surveyed specifications Agents Living specifications rebuilt from the current behaviour, in state Surveyed until the maintainer approves them
Gaps Agents A document of gaps only (missing tests, undocumented parts, risks), without documenting again what already exists
Index Engine A lexical and structural index, updated incrementally, queried through the engine

Evidence, not plausibility

Answers distinguish observations, limits and unknowns, and "not found" is a valid answer. This is what keeps an agent from inventing an architecture.

No embeddings

The index is lexical (BM25) and structural (tree-sitter symbols): fast, deterministic and repeatable. Embeddings would add a model, a store to maintain and results that are not repeatable, to help only with natural-language questions. Teams that want semantic search use an external tool next to Wayloop. See ADR 0004.

Saving tokens

  • A map within a budget instead of whole files.
  • Filtered reads of specifications: only the requirements that matter to the step.
  • Compact JSON output from every command.
  • For shell output, integration with an existing output compressor rather than a rewrite.