intent-overview

name	intent-overview
description	Read-only aggregation skill that reads the scattered .intent/ artifacts and generates a formatted read-through/overview view under .intent/overview/ as a derived view. Never modifies any canonical artifact.

intent-overview Skill

writes are limited to under .intent/overview/. Canonical .intent/*.md files are read-only, and generated output is derived.

Core Mission

• Success Criteria:
  • Reads the existing scattered .intent/ artifacts (intent-tree / intent-compass / packets index & active / packets/plan / export-log / deltas / mode / drift-log) read-only, and generates a formatted overview view that humans and agents can read through at once at .intent/overview/overview.md (R1.1)
  • On re-run, regenerates the overview from the latest artifacts by full replacement, producing no duplication of the source of truth (idempotent regeneration. R1.3)
  • When .intent/ or a required artifact (e.g. intent-tree) is absent, writes nothing, states the absence explicitly, and guides the user to the skill to run first (e.g. /intent-discover) (R1.4)
  • Makes clear that the output is derived / regenerable / not the source of truth (and Git-untracked) (the reader's concern takes priority, so this may be relegated to the end of the view. R1.5)
  • Organizes the whole picture into concern-separated derived views (intent view / dependency-block view / progress view), reflecting progress not as a single percentage but along axes of differing nature
  • When the user asks in natural language for an "understanding map", "pre-start briefing", or "understanding gap sorting", generates .intent/overview/agent-understanding-map.md / .intent/overview/active-packet-briefing.md / .intent/overview/understanding-gaps.md as derived views, without writing to any canonical .intent/*.md
  • After the three separate readings and at most one human decision candidate at the top, lays out all packets as a single progress rail with the five signals + [current stage → next stage(s) to pass through] (read-only, without computing or inferring state)
  • Aggregates while keeping canonical intent distinct from inferred intent, and design intent distinct from implementation reality; marks gaps and unobserved areas as "unfilled / unobserved" and never fills them in by guessing
  • Does not call other skills directly; coordinates only via read-only access to scaffold files (.intent/*.md) and guidance in the output text (R6.5). Has no state machine / autonomous loop / resident process, and maintains zero external dependencies (R6.1 / R6.2)

Execution Steps

Step 1: Confirm .intent/ and required artifacts exist (fail-fast)

• When the user requests generation of an overview view, first confirm that the .intent/ directory exists.
• If .intent/ or a required artifact (at minimum .intent/intent-tree.md) is absent, write nothing, state the absence explicitly, guide the user to the skill to run first (e.g. /intent-discover), and stop (fail-fast. R1.4). Do not create or update .intent/overview/overview.md at this point.
• Read .intent/mode.md (do not stop if absent; the enforcement / drift-watch values are referenced in later steps. Read-only — never modify it).

Step 2: Read sources and aggregate by delegating to the four rules

• This skill has no analysis / recovery / inspection logic of its own. The exact reading rules for each concern are delegated to the following four rules (referenced by relative path). Follow the exact headings, keys, and column names each rule specifies; keep canonical and inferred distinct; and state gaps and unobserved areas (never fill in by guessing).
• rules/aggregate-sources.md — intent-document aggregation (intent-tree L0–L4 / intent-compass North Star, Anti-direction, Invariants, Decision Rules / packets index & active / plan / export-log / deltas). Separate canonical intent from inferred intent (derived from intent-tree's Assumptions / Open Questions). Code recovery is read-only from the refactor-mode algo-intent-recovery output; do no AST / scanner recovery of your own. If recovery output is absent, state the absence and guide the user to that algo (R2.x / R4.x).
• rules/mermaid-tree.md — render intent-tree's L0→L4 as a pure Mermaid graph, with the corresponding text hierarchy alongside it as the source of truth. If intent-tree is empty/ungenerated, omit the Mermaid figure and state why (R3.x).
• rules/gap-readout.md — read the drift-log and intent-validate inspection axes without reimplementing them, and aggregate them as the "design intent vs implementation reality" gap. Aggregate drift only when mode.md's ## Drift-watch section is on and drift-log.md exists; when off / unspecified / absent, omit that block and state it as unobserved. Map validate axes to the stable kebab-case ID catalog in validate-checks.md. The ## Enforcement / ## Drift-watch sections are read-only — never modified (R5.x).
• rules/progress-readout.md — split progress not into a single percentage but into 3 axes (intent stability / realization completeness / evidence certainty), deriving each axis from reading existing artifacts and stating its provenance. Present axis-to-axis divergences as-is without collapsing them. Read packet frontmatter depends_on to derive block state read-only (dependencies are only read from declarations, never inferred or computed), and surface cycles / unresolved dependencies. Organize into concern-separated derived views (intent / dependency-block / progress). Omit any axis or view whose source artifact is absent, stating "unobserved / ungenerated" (R8.x / R9.x).
• Branching policy: branch on whether inferred intent is present and on drift-watch on/off; when absent, omit the relevant block and state its status (never fill in by guessing). For backward compatibility, read an existing packet without as "no dependencies", without as "unfilled", and the old 3-value state ()'s as "in progress (equivalent to implementing)" (follow the rules' specifications).

Step 3: Write the overview view last (full replacement, derived)

• Only after all reading and aggregation are complete, last write .intent/overview/overview.md by full replacement (idempotent regeneration. R1.3). Never write to any canonical .intent/*.md.
• Only when an additional derived view is requested by natural-language trigger, full-replace .intent/overview/agent-understanding-map.md / .intent/overview/active-packet-briefing.md / .intent/overview/understanding-gaps.md within the same write boundary. A default run may generate them, but must always mark them as non-canonical and timestamped, and must not treat them as diffs against the source of truth.
• The composition order of the content follows "Output Description" (the three separate readings and human decision candidate first, then the progress rail and concern-separated views, with the derived / not-the-source-of-truth notice at the END).
• That this view as a whole and each derived view is derived / regenerable / not the source of truth / Git-untracked is made explicit in the end-of-view notice (R1.2 / R1.3 / R1.5 / R9.5).

Output Description

The output target is the terminal. Use no raw HTML (<details> / <summary>, etc., collapsible UI) in the output; separate details with plain Markdown headings instead (in a terminal the raw tags are shown literally and become unreadable). Internal notations such as [[...]] (wikilinks for memory / delta) are legitimate in records written to delta / memory files, but in human-facing terminal output do not emit them raw — open them into ordinary words (spell the linked name out in plain prose).

Reader: a human developer who wants to read through the whole of .intent/ (and the AI that reads it downstream). What this output makes them grasp first: the separate Process health, Unresolved design decisions, and User outcomes readings, plus at most one uniquely evidenced human decision; the progress rail follows them.

Compose the head of the view in the following order (the order that gets a human to "where am I / what happens next" by the shortest path).

First show Process health, Unresolved design decisions, and User outcomes as separate short readings. Process health comes from packets and the progress rail; Unresolved design decisions come from explicit Open Questions / decision candidates; User outcomes come only from explicit outcome evidence. Without outcome evidence, label User outcomes unobserved and never infer them from process progress. Do not collapse the readings into an overall PASS, overall score, or "everything is healthy." Overview creates no second next move: it may foreground at most one uniquely evidenced human decision; otherwise it points to /intent-status for its single "What the human decides next" item.

1. Progress rail (after the three readings): lay out all packets vertically and annotate each row with the five signals (✅ reflected / 🔵 you are here / ⚪ not started / 🔴 unreflected / ◻ merged), followed by [current stage → next stage(s) to pass through] (per progress-readout.md "Annotate each row with [current stage → next stage(s) to pass through]"). This makes "which P is you-are-here now and which stages remain after this" and "where the unreflected / remaining work are" visible at a glance on a single sheet.
2. Concern-separated derived views (the rail's breakdown):
   • Intent view: the Mermaid figure of intent-tree (L0–L4) + the text hierarchy, intent-compass, and the packet list (with plan / export-log / deltas alongside as context). Canonical and inferred kept distinct.
   • Dependency-block view: dependency relations based on packets' depends_on and the resulting block state (with cycles / unresolved dependencies surfaced if any).
   • Progress view: the 3 axes (intent stability / realization completeness / evidence certainty) with each axis's provenance, axis-to-axis divergences, and the design-intent vs implementation-reality gap aggregation (since the progress rail is brought to the top in 1., concentrate here on the breakdown of the 3 axes).
3. End-of-view notice: that this view as a whole and each view is derived / regenerable / Git-untracked and not the source of truth (R1.2 / R1.3 / R1.5 / R9.5). Any view or axis without source material is omitted, with the reason (unobserved / ungenerated) stated.
4. The pointer to the intent coverage map (one line; every run): append to the end-of-view notice "run /intent-overview with a target range (a directory etc.) to generate a map of where in that range nothing governs the code (the intent coverage map) into .intent/overview/coverage-map.md" (if a generated coverage-map.md already exists, also state its generation time). On a run with a target range specified, replace this pointer with the map-generation result (the blank count and the output path) after the concern-separated views.
5. Pointer to understanding-support views (on a natural-language trigger): when "understanding map", "pre-start briefing", or "understanding gap sorting" is requested, state the generated derived-view path (.intent/overview/agent-understanding-map.md / .intent/overview/active-packet-briefing.md / .intent/overview/understanding-gaps.md) and the source files used. If no file was generated, state which source material was missing.

Plainness check for reports (user-facing reports; right before output; shared)

Right before emitting a user-facing report (progress, completion, items needing confirmation — including the end-of-turn summary), run this check (INV105, DR208). It applies only to user-facing report text, not to how internal records (canonical files and logs under .intent/) are written.

• Do not transcribe internal documents verbatim: text you just read or wrote in internal artifacts (tree, compass, packets, Open Questions) is written in internal vocabulary. In the report, restate that content in words a first-time reader understands (without changing facts or meaning).
• Identifiers must not be the subject of the sentence: when presenting an item to confirm or a unit of work, first write one sentence that stands on its own ("what and why"), then append identifiers (Open Question numbers, packet names, symbols, stage names) after it as references (e.g. "... please verify this before starting (ref: OQ-xxx-1)"). Do not delete identifiers or references to records for the sake of plainness (the trail back to the record is lost).
• Signal for overload: three or more unexplained internal terms in one sentence signal overload (read by meaning, not by mechanical count). If a sentence does not stand on its own, rewrite it in plain words before sending (without changing facts or meaning).
• Do not convey meaning only through a metaphor or a vague qualifier: the foundation of a report is precision — write so the meaning reads unambiguously (plain language is a means of staying easy to read while preserving it). Do not report results only with ungrounded qualifiers (e.g. "significantly", "nicely"); state observable facts. If you use a metaphor, pair it immediately with a precise restatement (do not force established technical terms, or ordinary words in their everyday sense, into strained paraphrases).
• This check works as a pair with the after-the-fact record (prevention alone is never enough): when a report failed to get through, log the case to the drift log while drift-watch is on, and feed the next prevention.

Safety & Fallback

• Does not call other skills directly: coordination happens only via read-only access to scaffold files (.intent/*.md) and guidance in the output text (R6.5). It holds no decision logic for recovery (algo-intent-recovery) / inspection (intent-validate) / drift (drift-watch); it only reads the outputs and definitions they leave behind.
• Has no state machine / autonomous loop / resident process (R6.1). The output view itself serves as a snapshot at read time.
• Zero external dependencies (INV2 / R6.2). Introduces no external package; limited to Node standard and natural-language heuristics.
• Does not modify application code (INV6 / R6.3).
• When prerequisites are absent: when .intent/ or a required artifact is missing, write nothing, state the absence, guide the user to the skill to run first (e.g. /intent-discover), and stop (R1.4).
• On partial gaps: when inferred intent is unfetched / drift-watch is off / intent-tree is empty, omit the relevant block and state "unfetched / unobserved / ungenerated" (never fill in by guessing). When Mermaid cannot be generated, present the text hierarchy as the source of truth, omit the figure, and note the reason.
• Safety boundary for understanding-support views: understanding maps, pre-start briefings, and understanding gap sorting are limited to rearranging existing artifacts and presenting candidates. They do not decide priority, change packet state, append Open Questions, or turn gaps into implementation tasks.