intent-discover

name	intent-discover
description	The entry point of Intent Planning. From the repository's pain points, README, and an overview of existing code, build an Intent Tree (L0-L4) and recommend/confirm the mode for working out the Intent. Does not implement.

intent-discover Skill

Core Mission

• Success Criteria:
  • The L0–L4 Intent Tree is structured, with canonical (confirmed) and inferred (guessed) separated
  • The mode for working out the Intent is recommended/confirmed and recorded in .intent/mode.local.md (the local canonical source for mode state)
  • Whether question delegation (designer-questions) is needed is confirmed and recorded in .intent/mode.local.md (the purpose as well when on; if deferred, it is noted in Open Questions)
  • Open Questions that the human should review are made explicit
  • For divergent work, the AI presents hypotheses, counterexamples, and alternative problem framings as inferred so the human can set decision boundaries in the next compass
  • A design principle is handed to downstream phases: explore broadly, have the human confirm decision boundaries in the compass, and keep implementation as bounded autonomy within those confirmed boundaries
  • When drift-watch is on, drift-prone-situation pre-check is performed, the matching pattern is named, and it is recorded in drift-log (when off, nothing is done)
  • No application code has been changed at all

Execution Steps

Step 1: Select the mode

• Read and apply rules/mode-selection.md.
• Check the available modes (.intent/modes/*.md) and recommend a mode based on the repository situation.
• Confirm by asking the user in natural language and waiting for their answer (run the recommend→confirm wiring even if standard is the only candidate).
• Create an issue directory and record the confirmed result there (A34 — resolving same-machine concurrent collision): on each discover run, create .intent/discovery/<slug>-<rand>/ (an issue directory mirroring packets; <slug> derived from the issue name; <rand> is 4 [a-z0-9] chars generated by the shell, no central numbering) and record the confirmed result in its mode.md (the local canonical source for mode state; not tracked by git). State the issue directory name in the Output so downstream skills inherit it for reading (reader identification). Keep the existing single .intent/mode.local.md as the backward-compatible legacy read target. Enforcement / Drift-watch (shared policy) stay in .intent/mode.md and are not touched. See .intent/discovery/README.md.
• Create one drafting claim (to tell parallel sessions "this is being drafted" — DR163/INV91): in the same step that creates the issue directory, create .intent/assignments/discovery-<issue-dir-name>-<session-rand>.md (<session-rand> = 4 [a-z0-9] chars generated by the shell). Its frontmatter: phase: drafting / issue_dir: <issue-dir-name> / packet_id: "" (no packet exists yet at drafting time — never fabricate an ID) / declared_at (shell date) / session / note (optional). Creation is automatic; deletion is manual (deciding that drafting has ended is a human judgment, so a machine never deletes a live claim; INV91). If a claim for the same issue directory already exists, do not create a duplicate (re-runs must not stack claims). Never stop or take over (a claim is read-only guidance and never refuses another session's start). The schema and its rules are governed by .intent/assignments/README.md; the reading contract lives in CONTRACT.md.
• Recommend → confirm → record the target format (optional, deferrable): after confirming the mode, when the target format (which exit to take = cc-sdd / openspec / speckit / to-spec / direct) can be inferred from the case, ask the user to confirm it, and on confirmation record it in the format line of .intent/mode.local.md. The inference signals are the case type (mode; whether the artifact is code or a document) and the setup markers of the downstream spec tools (whether .kiro/ for cc-sdd, a repository-root openspec/ for OpenSpec, or a repository-root .specify/ for Spec Kit exists; read-only observation); the format→exit correspondence and the handling of setup status (set-up tools first; never drop the not-set-up ones from the candidates; never invent a priority among set-up tools) are kept consistent with intent-packets/rules/export-route.md (the exit decision lane, the single source of truth) — do not copy its tables into this file. Choose direct for a case implemented directly without a tool (no spec tool launched — e.g. a small-to-medium change that edits code or documents directly); recording it lets /intent-writeback use that record as the primary signal for target identification (INV34). Follow the same confirmation discipline as mode / designer-questions / purpose: if it cannot be inferred, or the user defers/declines, do not fill it in by guessing — do not record it (continue with it unspecified; the exit decision later falls back to inference; if direct is likewise unrecorded, writeback falls back to the 3-condition AND inference). Recording the format is optional; discover continues as before even without it. Only /intent-discover writes the format (other skills read it read-only — DR26).
• Read rules/designer-questions.md and confirm/record question delegation (designer-questions).

Step 2: Apply the algorithm according to the mode definition

• Read the confirmed mode definition (e.g. .intent/modes/standard.md).
• Open the mode definition that .intent/mode.local.md's definition (falling back to the old .intent/mode.md) points to, and read and apply the algo rule (rules/algo-*.md) assigned to the Intent Tree construction phase (standard → rules/algo-gore-lite.md; refactor → rules/algo-gore-lite.md + rules/algo-drift-analysis.md, plus rules/algo-intent-recovery.md for intent-less code). The examples are not exhaustive; the mode definition's table is always authoritative.

Step 3: Build the Intent Tree

• Following GORE-lite, decompose L0 (purpose) → L1 (outcomes) → L2 (capabilities) → L3 (behavior/architectural intent) → L4 (candidate packets).
• Separate confirmed intent from guesses (Assumptions). Put anything undetermined into Open Questions.
• If an existing .intent/intent-tree.md exists, read it and present additions/updates as a proposal rather than overwriting.
• Only when multiple solutions are plausible, present competing hypotheses, counterexamples that could break each hypothesis, and alternative problem framings. With question-depth standard, keep them few and grounded; with deep, explore more broadly. Put all three in L3 (inferred) / Assumptions / Open Questions, do not promote them to canonical, and do not choose a solution here. Do not run this ritual for a self-evident case.

Step 3.5: Drift-Prone-Situation Pre-Check (drift-watch)

• Check the value of drift-watch in the ## Drift-watch (user-managed) section of the .intent/mode.md read in Step 1. When it is not on (including off, unspecified, invalid value, missing section, or missing mode.md), do not perform drift-prone-situation pre-check; continue to Step 4 as before (byte-identical to current behavior).
• Only when it is on, read and apply rules/drift-terrain.md. The symptom × in-progress Intent Tree matching, the named presentation of matching patterns, drafting anti-direction / invariant candidates into Open Questions, and appending to drift-log are all delegated to the rule's procedure (do not duplicate the procedure here).
• Only the constraint-starter matching runs always, regardless of the drift-watch value (A40, DR83 host ④): the "Constraint starter awareness (always)" section of that rule applies even when drift-watch is off / unset / invalid (made always-on because noticing conventions at the case's first stage minimizes rework; user-confirmed 2026-07-04). Keep the drift-prone-situation pre-check (drift-patterns matching) on-only as above; only the convention matching is made always-on. It is a light match: pull only the relevant domains and stay silent if the fit is weak (skip if the catalog is absent; do not stop).

Step 4: Present

• Present the proposed update to .intent/intent-tree.md.
• Apply the additional Intent Tree confirmations in rules/designer-questions.md (L1 measurement criteria / screen rough), following the rule's applicability conditions.
• Do not make implementation changes. Do not jump ahead with refactoring proposals.

Output Description

Reader: the human developer about to start pinning down intent. What this output makes them grasp first: "The skeleton of the Intent Tree is in place. Next is intent-compass. The only Open Questions to answer before confirming are these." In Codex, do not present /intent-compass as a slash command; guide the user with a natural-language prompt such as "run intent-compass" (the same applies to Gemini CLI, which reads this shared skill tree).

Lead with the conclusion.

• Next move (first, one line): "Run intent-compass" (building the decision criteria; define the Invariants/Anti-direction that prevent local optima).
• Open Questions needing confirmation: points the human must settle (left as questions rather than filled in by guessing). Framed so it is clear that clearing just these is enough before moving on.
• Details (proposed artifact updates): the proposed update to .intent/intent-tree.md (L0–L4 / Open Questions / Assumptions; canonical and inferred kept distinct), the confirmed mode and this run's issue directory name .intent/discovery/<slug>-<rand>/ (inherited by downstream skills — A34), and the confirmed designer-questions / purpose.
• Compass handoff (required when divergent): State this design principle: "During exploration the AI proposes hypotheses, counterexamples, and alternative problem framings provisionally; the human confirms decision boundaries in intent-compass; later implementation acts autonomously only within the boundaries confirmed by that compass and its packets." Hand unresolved boundaries over as Open Questions; do not settle them in discover.

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

• If the input (problem / target scope) is ambiguous, do not fill in with guesses; ask the user in natural language and wait for their answer.
• If an existing Intent Tree exists, do not destroy it; present the diff as a proposed update.
• Do not change application code.