intent-from-spec

name	intent-from-spec
description	Inward skill that reads user-provided natural-language text (specs such as PRD / issue / user story, plus fragmentary notes, scribbles, and voice transcripts) read-only and ingests unstated intent candidates and gaps of silence into `.intent/spec-ingest/`. Fragmentary input is bundled by topic and sorted into decided / undecided before extraction.

intent-from-spec Skill

Core Mission

• Success Criteria (success if achieved; the extract / check / sort / recap procedure detail is consolidated into Execution Steps, and only the outcomes are declared here):
  • Reads the natural-language text (a spec or fragmentary notes) read-only and extracts intent candidates for purpose, outcomes, capabilities, invariants, constraints, anti-direction, and implicit assumptions, marking them all as Assumptions (inferred intent) and never mixing them with canonical (confirmed intent) (Step 1–2. R1.1 / R1.2)
  • When the input is fragmentary notes / scribbles / a voice transcript, bundles the fragments by topic (clustering) and sorts them into "decided / undecided" before the 7-category extraction, presenting every bundle and mark with the inferred marker (without over-rewriting the person's words). For organized-document input this pre-stage does not trigger and the existing output structure is unchanged (C49, DR113)
  • Limits input to that spec text and does not use source code, execution traces, or test results as extraction input (R1.4). Picks up the spec's technical / security requirements without dropping them as Compass Invariants candidates, limiting their destination to Invariants (reflection into tech.md / design delegated downstream. R1.5 / R1.6)
  • When no spec text is provided as input, performs no extraction, asks the user for the spec to ingest, and stops (fail-fast. R1.3)
  • Reads the existing rulers (the inspection catalog in validate-checks.md and the common-core slots in decision-slots.md) against the spec and enumerates the unfilled items as gaps, showing in an observable form which category / slot each is the silence of, and presenting it as a hypothesis rather than a confirmed defect (R2.1 / R2.2 / R2.3). Does not stop processing while presenting; limits to warnings / awareness (same stance as drift-watch. R2.4)
  • Qualitatively sorts the extractions / gaps by load-bearing, presenting high distinctly from low. The judgment merely reads and copies the "front-load / defer door" column in decision-slots.md, and holds no mathematical solver, numeric score, or threshold (R3.1 / R3.2 / R3.3)
  • Summarizes "what was checked and what was left unfilled" as an omission recap, prompting reconfirmation (R4.1)
  • Treats only approved items as candidates for canonical promotion, retains unapproved items as Assumptions without discarding them, performs no auto-reflection, and delegates promotion to the user's manual copy (R4.2 / R4.3 / R4.4)
  • Limits output to derived artifacts under .intent/spec-ingest/, and never modifies any canonical .intent/*.md, application code, or the input spec (read-only. R5.2). Follows the intent-* naming convention and does not modify external spec tools or the kiro-* development environment (R5.6)

Execution Steps

Step 1: Confirm the input (natural-language text) exists (fail-fast)

• When the user runs /intent-from-spec, first confirm whether the natural-language text to ingest — an organized spec or fragmentary notes / scribbles / a voice transcript — (a file path or pasted body) is provided.
• If no text is provided, write nothing, state the absence of the input explicitly, ask the user to provide the text to ingest (a path or pasted body), and stop (fail-fast. R1.3). The same applies to empty or few-word fragments (when there is no material to bundle, generate nothing and say so). Do not write anything under .intent/spec-ingest/ at this point.
• Do not use source code, execution traces, or test results as extraction input. Recovering intent from those is a separate path handled by behavior-unknown mode's code→Intent, outside this skill's scope (R1.4).
• The ruler sources of truth (intent-validate/rules/validate-checks.md / intent-packets/rules/decision-slots.md) and the canonical .intent/*.md (intent-tree / compass / mode, if present) are referenced read-only in later steps. Do not stop if absent (state the absence for anything that cannot be linked).

Step 2: Delegate to the four rules to extract, check, sort, and recap

• This skill has no extraction / checking / judgment / scoring logic of its own. The exact reading, transcription, and linking rules for each concern are delegated to the following four rules (referenced by relative path). Follow the exact headings, transcription destinations, and ID systems each rule specifies; mark all extracted candidates as Assumptions; only read the rulers without reimplementing them; and state gaps and unobserved areas explicitly without filling them in by guessing.
• rules/extract-intent.md — reads the input text and extracts intent candidates across the seven categories of purpose / outcomes / capabilities / invariants / constraints / anti-direction / implicit assumptions. When the input is fragmentary notes / scribbles / a transcript, first follows the rule's "Handling fragmentary input" section before the 7-category extraction: bundling by topic (clustering) and sorting into "decided / undecided" (every bundle and mark carries the inferred marker; the person's words are not over-rewritten; not triggered for organized documents). Marks all candidates as Assumptions and writes each out with a heading and granularity whose transcription destination (intent-tree's L0–L4 Assumptions / compass's Invariants, Anti-direction, Decision Rules) is uniquely determined. Picks up the must-hold constraints such as technical / security requirements without dropping them, as compass Invariants candidates, and limits their destination to Invariants (reflection into tech.md / design is not included in the output = delegated downstream. R1.1 / R1.2 / R1.4 / R1.5 / R1.6 / R5.1).
• rules/gap-readout.md — reads the stable kebab-case inspection IDs in validate-checks.md and the common-core 8 slot IDs in decision-slots.md, and enumerates the items unfilled against the input spec as gaps. Shows which ruler's silence each gap is (ID linking) and which category / slot's silence it is (observable evidence), and presents it as a hypothesis rather than a confirmed defect. Defines no new inspection IDs / slot IDs of its own. Since spec-ingest is a proposer, not an acceptance gate, it may infer slot applicability from the spec's silence but does not confirm (a different posture from validate). Does not stop processing; warnings only (R2.1 / R2.2 / R2.3 / R2.4).
• rules/load-bearing.md — for the gaps / intent candidates that gap-readout linked to slot IDs, qualitatively sorts high/low by merely reading and copying the "front-load / defer door" column in decision-slots.md. "Front-load" = high (dangerous if it falls), "deferrable" = low. Holds no mathematical solver, numeric score, or threshold, and invents no new discriminating axis. Items that cannot be linked to a slot ID are stated as load-bearing-unknown (absence). Presents high distinctly observable from low, and retains low without discarding it (R3.1 / R3.2 / R3.3).

Step 3: Write the derived view to .intent/spec-ingest/ last (full replacement, derived)

• Only after all extraction, checking, sorting, and recap are complete, last write .intent/spec-ingest/spec-ingest.md by full replacement (idempotent regeneration). Never write to any canonical .intent/*.md (intent-tree / compass, etc.), steering (tech.md), design, or the input spec.
• In the view header, declare that this view is derived / regenerable, not the source of truth, and Git-untracked, and that all intent candidates / gaps / load-bearing levels described are Assumptions (hypotheses) and remain provisional until the user's approval (R1.2).
• Compose the output per extract-intent's transcription-destination headings, at a granularity the user can copy 1:1 into intent-tree's Assumptions / compass's blocks (keeping the promotion seam manual).

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).

• .intent/spec-ingest/spec-ingest.md (derived, regenerable, Git-untracked; the view header declares it is not the source of truth and that all items are Assumptions). The output contract of Step 2's four rules is canonical (not re-listed here). Skeleton only:
  • Bundling and sorting (fragmentary input only) — per extract-intent's "Handling fragmentary input", places the topic bundles and the "decided / undecided" marks (all with the inferred marker) before the 7-category extraction, appending at the end the note that this output can be passed to /intent-discover as-is. This section does not appear for organized-document input.
  • Intent candidates (extraction) — per extract-intent, presents purpose / outcomes / capabilities (→ intent-tree L0–L4 Assumptions), Invariants candidates (→ compass Invariants, incl. technical / security constraints), Anti-direction candidates (→ compass Anti-direction), implicit-assumption candidates (→ intent-tree Assumptions / compass Decision Rules) with uniquely-determined destination headings, each carrying its extraction basis.
  • Gaps (silence) — enumerates as hypotheses the gaps that gap-readout linked to IDs in validate-checks.md / decision-slots.md, with which category / slot's silence each is.
  • Load-bearing sorting — presents high distinctly from low (e.g. high at the top). Items not linkable to a slot are stated as load-bearing-unknown.
  • Omission recap — a list of the frames checked / filled / unfilled / could-not-check areas, plus promotion guidance for the user to transcribe approved items by hand into discover / compass.
• Categories / axes without source material are stated as "no relevant description (silence) / unobserved" and omitted (never filled in by guessing).

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

• Write boundary: writes are limited to under .intent/spec-ingest/. The canonical .intent/*.md (intent-tree / compass / mode, etc.), the ruler sources of truth (validate-checks.md / decision-slots.md), steering (tech.md), design, and the input spec are read-only — never created, modified, or deleted there (the Write in the frontmatter is permitted solely for writing under .intent/spec-ingest/. R5.2).
• Gaps are hypotheses (warnings only — never stop): gaps, load-bearing levels, and intent candidates are all Assumptions (hypotheses), not confirmed defects / severities. While presenting them, never stop processing; limit to warnings / awareness (same stance as drift-watch. R2.3 / R2.4).
• Approval gate — promotion is manual: reflection into canonical requires the user's explicit approval. Treat only approved items as candidates for canonical promotion, and retain unapproved items as Assumptions without discarding them. Perform no auto-reflection into canonical. Promotion is a manual copy in which the user carries approved items by hand into the discover / compass dialogue; spec-ingest does not call discover / compass, and discover / compass do not auto-read spec-ingest's output (no machine handoff = no hidden shared ownership. R4.2 / R4.3 / R4.4).
• Does not reimplement the rulers: never runs inspections / slot verification of its own; only reads the ID catalogs in validate-checks.md / decision-slots.md and the "front-load / defer door" column. Holds no inspection IDs / slot IDs / scoring / weighting engine of its own.
• Zero external dependencies (INV2 / R5.3). Introduces no external package, AST parser, or mathematical solver; limited to Node standard and natural-language heuristics, completing extraction within a natural-language workflow.
• Does not modify application code (R5.2). In the intent-planning phase, modifies neither application code nor the input spec (read-only).
• Naming / no external modification: follows the intent-* naming convention and does not modify external spec tools or the kiro-* development environment (R5.6).
• When prerequisites are absent: when no input spec text exists, write nothing, state the absence, ask the user to provide the spec to ingest (a path or pasted body), and stop (fail-fast. R1.3).
• On partial gaps: for any of the seven categories the spec is silent on, gaps that cannot be linked to the ruler catalogs, and items that cannot be linked to a slot and are load-bearing-unknown, state the area explicitly as "no relevant description (silence) / absent / unknown" and omit it (never fill in by guessing).