Understand
A skill that reads an existing understand-anything knowledge graph and writes squadron
planning documents from it.
This skill is a consumer. The graph is produced by the upstream understand-anything marketplace
plugin's own /understand command; this skill never runs, wraps, forks, or installs that plugin. If
no graph exists, this skill stops and says so rather than analyzing the codebase itself.
When invoked as $analysis-understand, follow the protocol below. Everything from here through the
--- divider is the protocol you execute. The section after the divider is documentation for humans
installing or maintaining this skill.
Note that /understand throughout this document names the upstream understand-anything plugin's
own command, which produces the graph this skill reads. It is not this skill and is not run by
this skill.
Preflight: Graph Contract
Run this entire section before writing anything. Every step below either succeeds, stops with a named reason, or records an explicit skip. No step is allowed to fail quietly.
Graph location and read discipline
Resolve the graph root:
- Run
git rev-parse --show-toplevel. On success, that is the repository root. - If
gitis unavailable or the directory is not a repository, use the current working directory as the root. This is a location fallback only — it does not suppress any check below. - The graph root is
<root>/.understand-anything/. The graph file is<root>/.understand-anything/knowledge-graph.json; the metadata file ismeta.jsonbeside it.
jq is required. Check it with command -v jq. If it is absent, stop and say that this skill
requires jq to read the graph safely. Do not fall back to reading the graph file directly — the
graph routinely exceeds a megabyte, and loading it whole defeats the purpose of every scoped read
below.
Every read is a field-scoped jq selection. The graph is never loaded whole into context, never
cat-ed, and never read with the Read tool. Only these selections are needed:
| Purpose | Selection |
|---|---|
| Key presence | jq -r 'keys[]' |
| Array lengths | jq -r '"\(.nodes|length) \(.edges|length) \(.layers|length) \(.tour|length)"' |
| Graph version | jq -r '.version' |
| Project identity | jq -r '.project | {name, description, languages, frameworks}' |
| Layers | jq -r '.layers[] | {id, name, description, count: (.nodeIds|length)}' |
| Layer membership | jq -r '.layers[] | {name, nodeIds}' |
| File-level nodes | jq -r '.nodes[] | select(.type != "function" and .type != "class") | {id, filePath, summary, complexity, tags, languageNotes}' |
| Tour steps | jq -r '.tour[] | {order, title, description}' |
| Edge aggregates | jq -r '[.edges[].type] | group_by(.) | map({type: .[0], n: length})' |
| Edge endpoints | jq -r '.edges[] | {type, source, target, weight}' |
Select only the fields named in that table. A node also carries name and lineRange; neither is
read by this flow.
Edge endpoints are read as strings, never dereferenced into nodes — see section 6 of the flow for the id-prefix parse that makes this possible.
Function- and class-level nodes are never read. They are the bulk of the graph and none of the sections this skill writes derive from them.
"File-level" means "carries a filePath" — a node that stands for a whole file. It is not a
synonym for type == "file". The architecture defines nine file-level types; this graph carries
file, config, and pipeline among them, and a future upstream release may add a tenth.
So the file-level filter is stated as an exclusion by name:
select(.type != "function" and .type != "class")
Not select(.type == "file"). The allow-list form silently drops every file-level type it was not
written to know about — on this graph it yields 201 nodes instead of 238, losing all 17 config and
20 pipeline nodes and quietly disagreeing with meta.json's analyzedFiles. The exclusion form
admits a new upstream file-level type automatically, which is the correct default: a file-level node
this skill has never heard of still stands for a real file.
Drift rule. A node that survives the exclusion but carries no filePath is reported as
upstream drift, naming the offending id. It is never silently counted or silently dropped — either
function/class are no longer the only non-file-level types, or the node is malformed, and both
are findings.
Also consumed by the comprehension flow, beyond the selections above — these were deferred by the 361 contract and are read by section 7 (coverage and scope limits):
config.jsonand.understandignorein the graph root — how the upstream plugin was configured and what it excluded, which is what lets a generated document state its own coverage limits.meta.json'sanalyzedFilescount, reconciled against the file-level node count.
Node type values beyond file, function, and class (this graph also carries pipeline and
config) are in scope — see the file-level definition above; they are the reason the filter is an
exclusion rather than an allow-list.
Validation: absent, unparseable, malformed
Run these three checks in order and stop at the first failure. The three messages must be textually distinct — a reader must be able to tell which failure occurred without inspecting anything else.
1. Absent — knowledge-graph.json does not exist at the graph root.
Stop. Report the path that was checked, and say that this skill consumes a knowledge graph produced
by the understand-anything plugin's own /understand command, which must be run first.
Do not guess whether the plugin is installed. State the build step and the install step as a condition, giving the commands for the surface you are running on (this file keeps both):
- Build the graph with the plugin's
/understand(on Codex, theunderstandskill). Say that this is a paid multi-agent run: on API billing a large repository can cost tens of dollars. - If the plugin is not installed, on Claude Code run
/plugin marketplace add Egonex-AI/Understand-Anythingthen/plugin install understand-anything. - If the plugin is not installed, on Codex run
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex.
2. Unparseable — jq empty <graph> exits non-zero.
Stop. Name the file and report that it is not valid JSON, quoting jq's own error. Say the graph is
likely truncated or partially written, and that re-running the plugin's /understand will rewrite
it. This message must not mention missing keys — the file never parsed, so no key was inspected.
3. Malformed — the file parses but its shape is wrong.
Required top-level keys, each with its required type:
| Key | Type | Empty is |
|---|---|---|
nodes |
array | reject |
edges |
array | reject |
layers |
array | reject |
tour |
array | warn, proceed |
version |
string | reject if missing |
project |
object | reject if missing |
Stop if any key is missing, is the wrong type, or — for nodes, edges, layers — is present but
empty. Name every offending key in one message, not just the first one found, so a single run
tells the reader everything that is wrong.
Report graph identity alongside the failure: version from the graph, and gitCommitHash and
lastAnalyzedAt from meta.json when they are readable. If meta.json is unreadable, say so rather
than omitting the line — identity is what lets a reader tell a stale graph from a broken one.
The tour asymmetry. An empty tour degrades exactly one section (suggested reading order), so
it warns and proceeds, and the affected section carries a gap marker. Empty nodes, edges, or
layers means nothing useful can be written, so it rejects. This asymmetry is deliberate: the test
is whether the missing field costs one section or the whole document.
Governing rule. If the upstream plugin renames or restructures a field, that must surface here as failure 3 — a loud, named rejection. It must never produce a document that is silently thinner because a selection returned nothing. A section that cannot be sourced is either a gap marker or a stopped run, never a quiet omission.
Staleness
The graph is a snapshot. This check reports how far the codebase has moved since it was taken. It warns; it never blocks — a stale graph still produces a useful document, provided the reader is told it is stale.
Read gitCommitHash from meta.json.
- If
meta.jsonis missing, or does not carrygitCommitHash, report that specific reason — "meta.json is absent" and "meta.json has no gitCommitHash" are different findings — and record the skip in the provenance block. Then continue. - If
gitis not on PATH, or the graph root is not inside a repository, announce the skip in console output and record it in the provenance block, naming which of the two applies. Then continue.
Never skip silently. A reader who is not told the check was skipped will assume it passed.
With a hash in hand, compare against git rev-parse HEAD. There are exactly three outcomes:
- Equal — report "graph matches HEAD".
- Different, and the hash is a known ancestor — confirm with
git merge-base --is-ancestor <hash> HEAD, then get the distance withgit rev-list --count <hash>..HEAD. Report "N commits behind HEAD". - Different, and the hash is unknown to this repository — the commit was rebased away, amended, or is absent from a shallow clone. Report drift with an unknown distance and say which of those the evidence supports.
Never fabricate a distance. If git rev-list --count cannot run or the hash is not an ancestor,
the honest answer is "unknown distance", with the reason. A made-up number is worse than no number,
because it reads as measured.
On any drift (outcomes 2 and 3), state the finding and ask the Project Manager whether to proceed
with the stale graph or stop and refresh it by re-running the plugin's /understand. If they choose
to proceed, record that in the provenance block as a PM decision — not as an incidental detail.
Every path through this check ends in one of: a distance, an explicit unknown-distance reason, or an explicit skip reason. There is no silent outcome.
.gitignore hygiene
The upstream plugin writes timestamped trash directories (.understand-anything/.trash-<epoch>/)
when it re-analyzes. These are churn, not project knowledge, and must not reach a commit.
Run this at the start of every run, before any document is written. A run that writes a document and then fails hygiene has already left the repository in the state hygiene exists to prevent.
1. Test whether it is already covered. Run:
git check-ignore -q .understand-anything/.trash-probe/
Exit 0 means some existing rule already covers the path — this skill's own entry, a broader
.understand-anything/, or anything else equivalent. Report "already ignored" and write nothing.
This is a semantic test, not a pattern grep. Grepping .gitignore for a literal string would
miss a broader rule that already does the job and would append a redundant entry. The probe path
does not need to exist — git check-ignore answers about the path, not about the file.
2. Append if not covered. Create .gitignore if it is absent. Append:
# squadron: understand-anything trash directories
.understand-anything/.trash-*/
3. Confirm. Re-run the check from step 1. Report the addition only after it passes. Never report a write you did not confirm.
Failure handling. Every failure is reported and non-fatal — hygiene never stops a run:
.gitignoreis read-only or the write is permission-denied → report that the entry could not be added and why, then continue.- The graph root is not inside a git repository → report that hygiene does not apply here, then continue.
Never claim a write succeeded when it did not. "Could not update .gitignore: permission denied" is a good outcome. Silence is not.
What is not ignored, and why. Everything in the graph root except the trash directories stays tracked:
knowledge-graph.json,meta.json,config.json,.understandignore— durable project knowledge. The graph is the input every document in this initiative derives from, and a tracked graph is what makes a generated document auditable after the fact.fingerprints.json— the plugin's incremental-analysis cache: acontentHashplus structural summary per analyzed file. Tracking it means a fresh clone's first re-analysis is incremental rather than a full rescan. It is regenerable, so it is tracked for the speed, not because it is authoritative.Exactly two things rewrite it, and neither is a side effect of using this skill:
- A deliberate re-run of the upstream plugin's own
/understandcommand. - The plugin's post-commit auto-update hook — but only when
autoUpdateistruein.understand-anything/config.json. The hook is gated on that key and the plugin's default isautoUpdate: false, so on a project that has never enabled it the hook never fires.
Reading a graph never writes fingerprints. Every squadron flow that touches the graph — this skill included — only reads, via the field-scoped
jqselections above. No number of runs of this skill will produce afingerprints.jsondiff. Expect churn when you refresh the graph on purpose, not when you consume it.- A deliberate re-run of the upstream plugin's own
intermediate/— the raw pre-analysis scan (file inventory, language and framework detection, import map) that feeds graph construction.
fingerprints.json and intermediate/ were not contemplated by the slice 361 design; they were
observed in a real v2.8.1 graph and are recorded here so a later author does not have to rediscover
what they are.
Squadron never deletes trash directories. The upstream plugin owns that lifecycle; this skill only keeps them out of git.
Document Conventions
Gap markers
When the graph does not supply something a section needs, say so in place. Do not omit the section, and do not fill it with plausible prose.
The marker is:
[GAP: {what is missing} — {which input would supply it}]
Both halves are required. "What is missing" alone tells a reader something is wrong; naming the input
that would supply it tells them what to do about it. Example shape: a marker for an empty tour names
the tour field and says that re-running the plugin's /understand would populate it.
Three rules:
- A marker appears twice — in the body, exactly where the content would have appeared, and in the provenance block's flagged-gaps line. The body placement tells a reader mid-document; the provenance placement lets them see every gap without reading the whole thing.
- A document containing gap markers is a valid output, not a failed run. Gaps are information.
- A gap is never filled with plausible prose. Inventing content that reads as sourced is the specific failure this whole contract exists to prevent.
[INFERRED] is a retained sibling convention, not a replacement. It comes from
project-documents/user/reference/analyze-codebase-prompt.md and prefixes a claim drawn from
indirect evidence. The two differ: [GAP: ...] marks something absent, [INFERRED] marks something
present but derived.
This flow does not use [INFERRED], and its appearance in a comprehension document is a defect.
Every claim in the comprehension document traces to a named field via the extraction mapping table
below, so nothing is left for [INFERRED] to mark. Where inference would go, the correct output is a
gap marker — the field is absent, and saying so is more useful than reasoning around it.
The one apparent exception is the closing observation a section may carry — a sentence that reads a pattern out of the data it just presented. Those are summaries of presented data, not new claims, and the test is mechanical:
If the closing sentence is not derivable from the data presented directly above it, it does not belong in the document.
[INFERRED] is not a license to add one. A conforming comprehension document contains zero
[INFERRED] markers — grep -c 'INFERRED' returns 0.
The marker stays documented in these shared conventions because Flow: Concept Generation genuinely
needs it: a concept's Solution Approach derived from tour ordering is an inference from indirect
evidence. Governance for that use is [INFERRED] governance for this flow, in that flow's
section below. Flow: Initiative Candidates does not use [INFERRED] at all — see that flow's
"Gap markers, [INFERRED], and read discipline" section for the structural reason.
Provenance block
Place a ## Provenance section immediately after the H1 title, above all content, as body prose.
Not frontmatter. Frontmatter is schema-validated and invisible to a reader scanning the document. The failure this guards against is a human reading a generated document and trusting it without knowing it was machine-written, derived from a stale snapshot, or missing sections. That warning has to be where they will actually see it.
The block carries these lines:
- Generated by — this skill, and the model id that produced the document.
- Generated on — the date of this run.
- Source — the graph path, with its
nodes/edges/layers/tourcounts. - Graph identity —
gitCommitHashandlastAnalyzedAtfrommeta.json. - Staleness — the outcome from the staleness check: matched HEAD, N commits behind, drift with unknown distance and its reason, or an explicit skip and its reason. If the PM chose to proceed with a stale graph, record that decision here.
- Section sourcing — each section of the document and the graph field it derives from.
- Flagged gaps — every
[GAP: ...]marker in the document, or an explicit statement that there are none. - Review state — always states the document is a machine-generated draft that has had no human review.
The block obeys its own gap-marker rule. If meta.json is unreadable, the graph-identity line
carries a [GAP: ...] rather than being dropped — consistent with how the staleness line records a
skip. No line is ever silently omitted: every one resolves from real data or carries a marker.
The review-state line is what makes status: not_started legible on a generated draft — it tells a
reader the status field means "not yet reviewed by a human", not "not yet written".
Slice 365 (capability (b)) reuses this same block shape, with Source naming the concept and initiative-plan paths instead of a graph.
Generated document conventions
Output path:
project-documents/user/analysis/{index}-analysis.codebase-comprehension.md
Index selection. Scan existing 9nn- filenames in project-documents/user/analysis/ and take
the lowest unused index ≥ 940. Each run takes a new index — runs are independent samples, not
revisions of each other, matching the existing 940/941/942 series. Never overwrite an existing
document. Overflow past 949 is sanctioned by the architecture; keep counting.
Frontmatter:
---
docType: analysis
project: {project name}
topic: codebase-comprehension
dateCreated: {YYYYMMDD}
dateUpdated: {YYYYMMDD}
status: not_started
model: {id of the model generating this document}
---
model: must hold the id of the model actually generating the document. Never empty, never a
placeholder, never copied from another document. cf validate frontmatter is permissive here and
will pass on a placeholder, so this requirement rests on the skill text, not on the gate.
If you cannot determine your own model id, say so explicitly and stop rather than writing a plausible-looking value. A wrong id is worse than a reported inability, because it silently misattributes the document.
model: on an analysis document is accepted by cf validate frontmatter — verified against
942-analysis.tech-debt-audit.md, which carries it.
Why status: not_started rather than a review-pending value: the status enum has no
needs_review member; complete would assert a review that has not happened. Review state is
carried by the provenance block, and not_started correctly reflects that no human has reviewed it.
Flow selection
This skill implements two flows. What the user typed after $analysis-understand selects between
them:
| What the user typed | Flow |
|---|---|
| nothing | Flow: Comprehension Analysis |
comprehension |
Flow: Comprehension Analysis |
concept |
Flow: Concept Generation |
candidates |
Flow: Initiative Candidates |
| anything else | unrecognized — say so and stop |
Any unrecognized text stops the same way — say it is unrecognized and stop; do not guess at intent.
Selection is by explicit argument only. The skill never infers a flow from repository state. The absence of a concept document never auto-triggers Flow: Concept Generation, and the presence of one never suppresses it. A flow runs because it was named. The presence or absence of a concept document selects nothing here either — it changes only what Flow: Initiative Candidates reads once it has been named.
Preflight runs in full for both flows, unchanged — location, validation, staleness, and the
.gitignore hygiene write, which the shared contract performs at the start of every run before any
document is written. Flow: Concept Generation adds no hygiene behavior of its own and skips none.
Flow: Comprehension Analysis
This is the default flow. Run Preflight: Graph Contract in full first — location, validation, staleness, hygiene — then extract and write.
Extraction mapping
This table governs the flow. Seven sections, in document order. Each row is binding: the section is written from those fields, ordered by that rule, and on absence emits that fallback and nothing else.
| # | Section | Source fields | Ordering rule | Fallback when absent/empty |
|---|---|---|---|---|
| 1 | Project identity | project.name, .description, .languages, .frameworks |
n/a (single block) | [GAP: ...] per missing subfield; project itself missing is a preflight rejection |
| 2 | Layer architecture | layers[] (name, description, nodeIds) |
descending file count | preflight rejects empty layers |
| 3 | Entry points | file-level nodes[] where tags contains entry-point |
layer, then filePath |
[GAP: no node carries the entry-point tag — re-run /understand] |
| 4 | Complexity hotspots | file-level nodes[] (complexity, filePath, summary, languageNotes) |
top ordinal tier, then layer | [GAP: ...] naming complexity |
| 5 | Suggested reading order | tour[] (order, title, description) |
order ascending |
[GAP: ...] naming tour; preflight has already warned |
| 6 | Dependency observations | edges[] (type, source, target, weight) |
descending count, ties by weight |
preflight rejects empty edges; an edge whose endpoint will not resolve to a layer is excluded from the tally and reported as drift, with the excluded count carried as a [GAP: ...] when non-zero |
| 7 | Coverage and scope limits | meta.json analyzedFiles; config.json; .understandignore |
n/a | [GAP: ...] naming the unreadable file |
Section ordering is identity → structure → detail → caveats. A reader who stops after section 1 knows what the project is; a reader who stops after section 2 knows how it is shaped. Coverage limits go last because they qualify everything above them and are meaningless read first.
The fallback column has no third option. Every section resolves to sourced content or a gap marker. A section is never omitted, never shortened silently, and never filled with prose that is not traceable to its named fields. This is the governing rule of the graph contract applied per section rather than globally.
Write exactly these seven sections, in this order. Each names its source graph field inline, in the body, so a reader can trace any claim without consulting this skill — the section-sourcing lines in the provenance block are in addition to that, not a substitute for it.
Inline attribution is required in every section. Each section body opens with a lead sentence
naming the fields it was written from — the established pattern is a short From \`.`
sentence, optionally carrying the one caveat a reader needs to read the numbers correctly:
From `layers[]`. Counts are `nodeIds | length`; layers holding non-`file` types carry a breakdown.
From `tour[]`, in `order`.
This is what makes a claim traceable at the point of reading. The provenance block's section-sourcing lines serve a reader scanning the top of the document; they do not discharge this requirement.
1. Project identity — from project.
project.name, project.description, project.languages, project.frameworks — a single block, no
internal ordering.
project.description is upstream-generated prose. Quote it and attribute it to the plugin. Never
restate it as squadron's own claim about the project: it is the graph's description of the codebase,
and a reader must be able to tell that apart from anything squadron asserts. languages and
frameworks are listed verbatim, not summarized or reordered.
Fallback: a [GAP: ...] marker per missing subfield, naming that subfield. A missing project
object as a whole is a preflight rejection (Validation step 3 above) and never reaches this
section — do not re-implement that check here.
This section supplies the concept document's Initial Technical Direction in Flow: Concept Generation, which is why identity is captured here rather than left to that flow.
2. Layer architecture — from layers[].
For each layer: name, description, and its node count.
Ordering: descending file count — the largest layer first, so the shape of the system is legible from the top of the section.
Fallback: none beyond preflight. An empty layers array is a preflight rejection (Validation
step 3), so this section is never reached without data and invents no marker of its own.
The count is nodeIds | length, directly. layers[].nodeIds holds only file-level nodes — no
function or class node appears in any layer. Intersecting with type == "file" undercounts every
layer that carries a non-file file-level type, and does so silently: on this repo's graph it
reports Packaged Declarative Content as 1 instead of 34, and Project Configuration as 2 instead of 6.
Report the type breakdown when a layer holds anything other than file nodes, so the count is
auditable rather than a bare number:
Packaged Declarative Content — 34 (config:13 file:1 pipeline:20)
Project Configuration — 6 (config:4 file:2)
A layer that is entirely file nodes reports its count alone; the breakdown would add nothing.
Cross-check, and its drift rule. Every nodeIds entry must resolve to a node carrying a
filePath. An entry that resolves to a function or class node — or to no node at all — is
reported as upstream drift, naming the offending id. It is never silently filtered out of the
count: filtering is what produced the wrong numbers this rule replaces.
jq -r '([.nodes[]|{name:.id,value:.type}]|from_entries) as $T
| .layers[] | "\(.name) total=\(.nodeIds|length) " +
(.nodeIds|map($T[.]//"UNRESOLVED")|group_by(.)|map("\(.[0]):\(length)")|join(" "))' \
.understand-anything/knowledge-graph.json
Any function, class, or UNRESOLVED entry in that breakdown is drift; report it.
3. Entry points — from file-level nodes[] whose tags contains entry-point.
The tag is the only signal. No filename heuristics — do not infer an entry point from main.py,
__main__, app.py, or any other naming pattern, and do not suppress one because its name looks
unlikely. A package __init__.py carrying the tag is reported as tagged. The tag is upstream's
judgment; this skill reports it and does not overrule it in either direction.
Selection — note the file-level exclusion, not type == "file":
jq -r '.nodes[] | select(.type != "function" and .type != "class")
| select(.tags and (.tags | index("entry-point"))) | "\(.type) \(.filePath)"' \
.understand-anything/knowledge-graph.json
Ordering: group by layer, report the count per layer with the paths beneath it. A flat list is the wrong shape here — this graph tags 28 file-level nodes, and grouping is what makes the distribution legible.
Function-level nodes also carry this tag (24 of them here) and are not read: they are not file-level, and the section reports files.
Fallback, verbatim: [GAP: no node carries the entry-point tag — re-run /understand].
4. Complexity hotspots — from file-level nodes[].
Fields: complexity, filePath, summary, languageNotes. File-level only
(select(.type != "function" and .type != "class") — see the file-level definition in the read
discipline above).
complexity is an ordinal string, not a number — observed values are simple, moderate, and
complex. Do not sort it numerically; sort_by(-.complexity) fails outright on a string, which is
the correct loud failure.
Report the full tier distribution first, then the top tier grouped by layer. The distribution gives the reader a denominator; the grouping is what makes concentration visible. Ordering within the section is top ordinal tier first, then by layer.
# distribution across all file-level nodes
jq -r '[.nodes[]|select(.type!="function" and .type!="class")|.complexity]
| group_by(.) | map("\(.[0]):\(length)") | join(" ")' \
.understand-anything/knowledge-graph.json
languageNotes is attached where present and omitted silently where absent. This is the one
sanctioned omission in the whole flow, and the reason is specific: languageNotes is a per-node
optional annotation, not a source field of the section. It is present on 97 of 238 file-level nodes
in this graph, and emitting a gap marker for each of the other 141 would bury the section in noise
that tells a reader nothing. Every other absence in this document still gets a marker.
A complexity value outside the observed ordinal set is reported as an unrecognized tier, named
explicitly, and never bucketed into a known one. Bucketing would silently move a file into a tier
upstream did not assign it.
Fallback: [GAP: ...] naming complexity.
5. Suggested reading order — from tour[].
Fields: order, title, description. Ordering: order ascending — the tour is a sequence and
reporting it out of sequence destroys the only thing it carries.
description annotates each step; it is not optional decoration, it is what tells a reader why the
step comes where it does.
Fallback: [GAP: ...] naming tour and the input that would supply it. Preflight has already warned
on an empty tour (the tour asymmetry above), but this section still emits its own marker — the
warning went to the console, and the document has to stand on its own.
6. Dependency observations — from edges[].
Fields: type, source, target, weight. Two parts, in this order:
- Edge-type counts across the whole graph — a
group_byover.edges[].type. - Inter-layer
imports/depends_onconnections, self-references excluded (a layer importing itself is not an observation), ordered by descending count with ties broken byweight.
Endpoint resolution is a string parse of the edge's own source / target id — not a node read.
Node ids are type-prefixed as <type>:<filePath>[:<name>], so the second colon-delimited field is
the owning file's path, and that path's file-level node gives the layer. Verified across all 925
nodes of this graph: the second field equals filePath exactly for every node of every type, and no
filePath contains a colon.
No node — and specifically no function or class node — is read to resolve an endpoint. This
is what keeps the dependency section consistent with the read discipline above while still counting
the edges whose endpoints are function-level.
Failure path — an endpoint that does not resolve. Both variants are excluded from the tally and reported as drift naming the endpoint id:
- The endpoint string does not parse as
<type>:<filePath>[:<name>]→ excluded, reported as drift naming the malformed endpoint id. - The endpoint parses but its
filePathmatches no file-level node → excluded, reported as drift naming the unresolved id.
Excluded edges are counted, and when that count is non-zero the section carries a [GAP: ...]
marker stating how many edges were excluded, so a reader knows the tally is partial and by how
much. An unresolvable edge is never silently skipped — that would make the counts wrong in a way
no reader could detect. In this graph, zero of 2184 edges have an endpoint absent from nodes, but
the code path exists regardless, because that is one graph.
Scope note — the fallback if the id-prefix contract ever fails. Only 16 of 610
imports/depends_on edges here touch a function or class endpoint (2.6%), so endpoint resolution
is a correctness guarantee for a small tail, not a load-bearing feature. If a future graph breaks the
id-prefix contract, restrict the tally to file-level endpoints and report the excluded count —
that loses little and stays honest.
7. Coverage and scope limits — from meta.json, config.json, and .understandignore.
Last section, because it qualifies everything above it. Three inputs, each with its own rule:
analyzedFiles from meta.json, reconciled against the file-level node count. Equality is the
expected case and is stated as such ("238 analyzed files, matching 238 file-level nodes"). A
mismatch is reported as a discrepancy carrying both numbers — never silently prefer either, and
never reconcile them by hand. A mismatch means the graph is internally inconsistent, which is exactly
what a reader deciding how far to trust the document needs to be told.
jq -r '.analyzedFiles' .understand-anything/meta.json
jq -r '[.nodes[]|select(.type!="function" and .type!="class")]|length' \
.understand-anything/knowledge-graph.json
config.json — report the settings that are present. Nothing more. An absent optional key is
not a gap: this is upstream's own file with upstream's own defaults, and squadron does not know
which keys are mandatory. This graph's file holds only outputLanguage; autoUpdate is absent, and
that absence is reported as nothing at all, not as a missing setting.
.understandignore — report the count of active patterns and list them. Active means uncommented
and non-blank (grep -vE '^\s*(#|$)'). This is what lets the document state its own coverage limits:
a reader can see what was never analyzed. A file whose lines are all comments or blank is
reported as "defaults only" — a real state, not a gap, because the upstream plugin ships this
file pre-populated with commented suggestions.
Fallback: [GAP: ...] naming the specific file that could not be read.
Do not add sections beyond these seven. The mapping table is the full scope of this flow. Concept generation is Flow: Concept Generation below and initiative candidates are Flow: Initiative Candidates below; neither is written here.
Register with cf
After the document is written, or rewritten by a refresh, run sq onboard register-comprehension
from the project root. It tells cf where the newest comprehension document is so cf's later phases
can cite it. If it exits non-zero, show its stderr line and carry on: the document is written, and
cf simply shows none registered until the command succeeds.
Flow: Concept Generation
Writes 000-concept.{project}.md for an existing codebase that has no concept document — the Phase 0
entry point for a repo that has never had cf/sq planning artifacts.
The governing rule of this flow: an existing codebase answers questions about its own nature through its artifacts, or not at all. Three machine-readable sources are extracted before any human contact. The human is asked exactly one category of thing — engagement context, the facts no artifact can hold — as two fixed questions, plus one confirm-or-correct on the derived description.
Run Preflight: Graph Contract in full first, then check the preconditions below, then extract, then interview, then draft, then confirm, then write.
Preconditions
The target scenario is a repo with no user-level cf/sq artifacts — no concept, no initiative plan. It is not a repo with no setup at all. Three preconditions, checked before extraction:
1. The graph is present. This is the shared Preflight: Graph Contract above, executed unchanged — location, validation, staleness, hygiene. Missing, malformed, and stale handling all belong to that contract; do not re-implement any part of it here.
2. The ai-project-guide is installed. The concept guide's layout is read at write time from:
project-documents/ai-project-guide/project-guides/guide.ai-project.000-concept.md
If the guide tree is absent, stop and name the setup step (cf init or /cf:onboard) that
installs it. This is a terminal precondition failure, not a gap — the document cannot be
correctly written at all, so no document is written.
3. The project name resolves from the cf project registration. Never from the graph — see
Output conventions below. If no registration resolves a name, stop, naming the setup step.
Deriving a filename from the graph's project.name is prohibited, so there is no fallback; this
failure is terminal, the same family as precondition 2.
Boundary with /cf:onboard. /cf:onboard owns project setup and the conversational, greenfield
concept path — a human describing what they intend to build. This flow owns the artifact-derived,
brownfield path — a machine drafting from what already exists. They compose (onboard installs the
scaffolding these preconditions require) and do not overlap: neither contains the other's
interaction model.
The three-source extraction model
Extraction runs against three sources, in the order below, before any human contact. Each source has a distinct attribution style, and the style is what makes a claim traceable at the point of reading.
Source 1 — the graph (structure).
Fields read: project.description, project.languages, project.frameworks; layers[] names and
descriptions; tour[] order; file-level nodes tagged entry-point; config nodes.
Attribution: each claim names its field inline, exactly as the comprehension flow does.
Read discipline: 362's discipline, unchanged — field-scoped jq selections only, the whole graph
never loaded, no function or class node read. This flow reads strictly less of the graph than
the comprehension flow does: no edges, no complexity tiers, no per-node summaries.
Source 2 — the repo's own prose (intent).
A repo's README states what it is, what problem it addresses, and who reaches it, in its authors' own words. That is the intent no graph field carries.
Where the README and project.description disagree, the README wins. project.description is
upstream-generated prose describing the repo as it stood when the graph was built; the README is
maintained by the project's own authors and travels with the code. A graph that is many commits
behind HEAD routinely c
…(truncated)