Step 2 - Review the draft

Goal: read what the agent proposed, before you judge it. The draft lives under .alloy-output/survey/your-repo/draft/ - gitignored and uncommitted. Open it.

The draft is a small set of files, each with one job.

source-entry.yaml (always present)

Exactly one source: your repo, as a self: true spoke source. It carries the discovery block the survey drafted - the scanners it picked, the units definitions that group raw candidates into documentable units, and a coverage: block if the source opted into coverage accounting. This is the heart of the draft: it decides what gets documented and how it is grouped.

A unit definition reads roughly like this:

units:
  - kind: service          # the unit type - fixes doc shape and rule pack
    match: services/{name}  # how raw candidates map to units
    groupBy: name
  - kind: lib
    match: packages/{name}
    groupBy: name

rulepacks/<kind>.yaml and rulepacks/templates/<kind>.md

Only for new kinds the draft introduces. A rule pack says which files feed a kind's doc and carries the extraction prompt for each; the template fixes the doc's sections. If the survey reused an existing kind, there is no new pack for it.

manifest-categories.yaml

The proposed categories.<kind> entries for the new kinds - where each kind's docs live in the corpus tree and how they are laid out. These get woven into the corpus manifest at install time.

units.yaml

Present only for the inventory tier - repos where nothing in the path predicts units, so the units are listed by hand. Most repos with a workspace manifest or a predictable layout will not have this file.

follow-ups.md

The agent's open questions, scanner proposals, and anything it wants you to decide. Read this first if you read nothing else - it is where the judgment calls surface. A survey that found a genuine ambiguity records it here rather than guessing past it.

Read the survey report too

Alongside the files, the skill's chat report gives you the parts that are not in the YAML:

• Decompositions considered - the unit grain it chose, the alternative(s) it rejected, and the coverage delta between them (every unit one grain captures that the other drops). This is the single most reversible decision in the whole draft; the report is where you get to veto the grain, not just the draft.
• The coverage triage - every exclusion it wrote and the rationale, plus any UNKNOWN it could not resolve.
• The ontology triage - each kind's definition, the members it tested against that definition, and any bundling it chose to record rather than split.

Don't fix anything yet

This step is reading, not editing. You are building a picture of what the survey saw in your repo. Step 3 explains how to judge each part; step 4 is where you change things.

Next: step 3 - Understand the draft.