survey: understand code nobody documented
An inherited codebase with no docs is risky to change and riskier to rewrite, because nobody can say what it
promises. survey indexes it, writes what it does with a citation for every claim, asks you only what the code
cannot answer, and drafts a backlog to modernise it.
| Field | Value |
|---|---|
| In plain words | Reads a codebase nobody documented, says what it does with a citation for every claim, and drafts the backlog to modernise it. |
| Journey stage | Shape the goal |
| Accountable seat | Code Architect (Vishwa) |
| Does the work | Vishwa, the Accountable seat's twin, in the plan model lane, with the seat's paired human when it has one |
| Consulted | Product Strategist (Arjun), Quality Architect (Yama) |
| Informed | Engineering Manager (Drona) |
| Layers it can touch | every layer |
| Who reasons | your agent's own model, inside the skill |
| Writes as | the bot identity (a GitHub App); without one, your identity, tagged as human fallback |
| Where it runs | the aayu command, a skill in your agent, an MCP tool (read-only unless [mcp] expose_writes is on) |
| The skill your agent reads | skills/survey/SKILL.md |
When to use it
- You inherited a legacy system, a library, or a prototype that became a product, and nobody can say what it does.
- You plan to rebuild it on a modern stack and need to know which interfaces others depend on.
- Before a rewrite, you want the old program's outputs captured so the new one can be proven to match.
Starting from an idea, not from code? Use grill. Planning one story in code you already know is
plan.
Run it
Ask your agent in plain words, naming the target if you want one. It indexes the code, reads it module by module, asks you a few questions a round, riskiest first, and shows you the backlog before anything is filed.
Use the survey skill on this repository: tell me what it does and who it serves, and draft a backlog to rebuild it
in Go.
aayu survey [<path>]
| Input | Required | What it does |
|---|---|---|
<path> |
no | Checkout to survey; default the repository root. |
--out |
no | Directory for the survey's files (index.json, SURVEY.md, backlog.md, golden/); default .aayudha/survey under the surveyed checkout. |
--budget |
no | Module size in tokens (about four bytes each) when grouping files; default 20000. |
--module |
no | Print one module's fact pack (files, targets, entry points, surfaces, markers, symbols, calls in and out) from the index; read-only. |
--docs |
no | User manuals and notes from outside the checkout (a file or a directory of text, Markdown, HTML, man pages, or PDF through pdftotext), indexed as manual:<name> documents a claim cites by line; their text is written under <out>/manuals. |
--draft |
no | Survey draft to check, whole or some of its sections (JSON: claims at the engineering, capability, and product levels, trap findings, the do-not-carry list, the compatibility contract, unknowns, answers, modernisation path): every claim cites the index, a manual, or a probe, or is marked unknown. Each section is saved with its findings under <out>/sections and resumed by later runs; with every section present it writes survey.json and renders SURVEY.md. |
--sections |
no | Report the survey sections saved under <out>/sections: which pass, which have problems, and which are missing or stale. |
--backlog |
no | Backlog draft to check (JSON: Goal, Initiatives, Features, Stories, Bugs, and do-not-carry Decisions) against the work-item schema, the survey draft, and its compatibility contract; renders backlog.md and its review digest. |
--create |
no | With --backlog: file the reviewed backlog as issues through the actions log, skipping items already filed; needs --reviewed. |
--reviewed |
no | With --create: the review digest of the exact backlog the person reviewed (printed by --backlog). |
--limit |
no | With --create: the most issues one run files; default 25. |
--golden |
no | Characterisation cases (JSON) to run against the legacy build (--bin), writing each case's stdout, stderr, and exit code with SHA-256 under golden/. |
--parity |
no | Characterisation cases (JSON) to replay against the new build (--bin) and compare with the golden outputs; exit 3 on any difference. |
--compat |
no | A legacy test suite as cases (JSON, each test with its suite and area) to run against the new build (--bin) after --golden ran it on the legacy build: scores passes per area, appends to compat-history.jsonl, exit 3 when a test the legacy build passes fails. |
--bin |
no | With --golden, --parity, or --compat: the program the cases run as {bin}. |
--run |
no | With --golden, --parity, or --compat: run the cases' program; without it the cases file is only checked. |
--shadow |
no | With --golden --bin <legacy> --run: the new program, run beside the legacy one on the same inputs; reports every difference without golden files, exit 3 on any. |
--probe |
no | With --golden --bin --run: also run each case twice and under a changed time zone, locale, and HOME (and under strace when installed), writing non-determinism, environment dependencies, and files read and written to probes.json. |
--check-bin |
no | With --probe: a sanitiser, checker, or differently optimised build of the legacy program; cases whose stderr carries a checker report, or whose stdout or exit code differs from the capture, are recorded. |
--coverage |
no | With --probe: an lcov tracefile from running the cases under coverage; records the index's functions the cases never reach. |
Proving a rewrite matches is aayu survey --parity cases.json --bin <new program> --run.
What you get back
Files under .aayudha/survey/: index.json, then SURVEY.md with every claim, its basis, and its citation, the
traps a port must check, what not to carry over, and the compatibility contract. backlog.md holds the draft Goal,
Initiatives, Features, Stories, and Bugs, with a review digest. Once you confirm it, the issues are filed with the
survey:<product> label, at most 25 a run by default. golden/ holds the legacy program's captured outputs.
You should see aayu survey --draft survey.json exit 0 once every citation resolves; it exits 4 while a problem
remains. --parity exits 3 and names the first differing line when the new build does not match.
Gates
It checks these before it acts, and stops when one fails:
- validator: The work item passes stage validation for its type.
- halt: The repository is not halted (aayu halt).
A backlog item never rests on a guess: an unknown becomes a question for you, and the item it would unlock waits.
In the merge gate, the parity floor replays the captured outputs, so a rewrite cannot merge while its contract
fails.
What only a person does
The registry reserves no step of this verb for a person.
You answer what only you know (who runs it, which interfaces must stay exact) and review backlog.md: filing needs
the digest of the exact backlog you reviewed. You accept each do-not-carry Decision with decide.
What's next
- Make the first filed story Ready:
ready. - Turn a goal into work items from scratch instead: the goal.
- Every skill.