intent-to-spec

name	intent-to-spec
description	Outward generation skill that reads Intent, steering, and packets within a given scope read-only and maps them into a single readable natural-language Spec under `.intent/nl-spec/` in the given format.
allowed-tools	Read, Glob, Grep, Write, AskUserQuestion
argument-hint	<source scope / format> (the scope hint and the layout. If no format is specified, the default is used and which format the output was generated in is stated explicitly.)

intent-to-spec Skill

Core Mission

• Success Criteria:
  • Reads, read-only, only the .intent/ artifacts within the user-specified scope (source scope: Intent subtree / packet group / steering constraints / cross-cutting requirements) as source material, and binds the three layers (the Intent's why / invariants / decision rules / steering-grade constraints / requirements' individual demands) across them (R1.1 / R1.2)
  • When the source scope is ambiguous, or the corresponding artifact is absent, generates no natural-language Spec and stops, showing the user what is ambiguous (the available scope) or which artifact is missing (the relevant skill to prepare it) (R1.3)
  • Treats the projection sources (intent-tree / compass / packets / steering) read-only, and does not create, modify, or delete them (R1.4)
  • Composes the natural-language Spec per the specified target format (the why-fronted upstream layout / the requirements-crossing integrated spec / their middle), and when no format is specified, uses the default and states explicitly in the output which format it was generated in (R2.1 / R2.4)
  • Satisfies trace assignment, inferred marking, invariant preservation, and the supplemented-places list (done in Step 4; R3.1 / R3.2 / R3.3 / R3.4)
  • Outputs the artifact as derived (regenerable) under .intent/nl-spec/ by full replacement, and never creates, modifies, or deletes any canonical artifact (intent-tree / compass / packets). Does not put operational boilerplate about derivation, source-of-truth status, Git tracking, or internal paths into the generated document (R4.1 / R4.2 / R4.3)
  • Does not modify application code in the intent-planning phase (R4.4). Follows the intent-* naming convention, does not modify external spec tools or the kiro-* development environment, does not call map-cc-sdd.md, and does not change the behavior of /intent-export-cc-sdd (R5.5)

Execution Steps

Step 1: Source interpretation (confirm scope and depth; do not generate if ambiguous/absent)

• Important-decision entry check: Check at the start of natural-language Spec generation. Read the in-scope Intent Tree, Intent Compass, packets, and their referenced Open Questions, then use the shared contract in CONTRACT.md to classify whether an item is an important decision requiring a human decision. For each important decision, present at least one provisional answer proposal, its rationale, and the condition that would change the recommendation. Until one of these outcomes is obtained from the user—a decision, out-of-scope for this work, or scope-limited explicit continuation—do not start natural-language Spec generation for the affected scope. Work outside the stopped scope may continue, and an ordinary Open Question that is not an important decision may continue as before. After an allowed outcome, update or recheck affected artifacts before resuming only that scope.
• When the user runs /intent-to-spec, first interpret the argument's scope hint, format specification, and output-depth specification per rules/source-scope.md. For any axis the arguments alone do not uniquely determine, ask the user via AskUserQuestion and wait for the answer before confirming (do not fill in by guessing).
• Output-depth confirmation (per the "output-depth axis" in rules/source-scope.md): confirm how deeply to write (brief / standard / detailed), riding the same dialogue completion as the range axes. When depth is made explicit in the arguments (e.g. "detailed," "in brief"), do not ask (do not add unnecessary questions). When it is not explicit, ask once, before generating, via AskUserQuestion (present the three levels as peers, without putting a "reasonable default" up front = anchoring avoidance). This is deliberately asymmetric to how format is treated when unspecified (silently use the default): missing thickness is invisible to the reader, so it is confirmed before generating (details in the corresponding section of source-scope).
• Output-form confirmation (DR189, multiple choice): confirm which form to output (Markdown / self-contained HTML / Marp slide Markdown), riding the same position as the depth confirmation. When the form is made explicit in the arguments (e.g. "in HTML," "and Marp"), do not ask (do not add unnecessary questions). When it is not explicit, ask once, before generating, via AskUserQuestion (multiple choice; present the three forms as peers). When unspecified / unanswered / dialogue is not possible, output only the default Markdown (backward-compatible; the default form is provisional). Write only the chosen forms in Step 5.

Step 2: Three-layer read (read the three layers read-only, read by depth)

• Per the "three-layer read (exact, fixed references, read by depth)" table in rules/source-scope.md, read the three layers across the confirmed scope read-only. The depth to read follows the confirmed output depth (brief=packets up to frontmatter+Evidence / standard=plus the key points of Expected Behavior / detailed=up to all sections of the packet body; the "reading depth by output depth" column is authoritative). At brief and standard, do not read the whole packet body (read only the sections the depth needs = do not load everything, DR6).
• Bind, as source material for a single document, the Intent's why / invariants / decision rules (.intent/intent-tree.md's L0–L4 / .intent/intent-compass.md's North Star, Invariants, Anti-direction, Decision Rules), the steering-grade constraints (only when specified, tech.md, etc.), and the requirements' individual demands (.intent/packets/index.md + .intent/packets/active/*.md).
• Hold canonical-derived material and inferred-derived material (intent-tree's Assumptions / Open Questions) distinct from the reading stage, and never mix them. Do not read out-of-scope artifacts. Treat the projection sources read-only and do not modify them (R1.4).

Step 3: Target-format mapping (when defaulting, state the format explicitly; vary thickness by depth)

• Per the confirmed target format, map the three-layer material bound by Step 2 — keeping the provenance of which layer / which heading / which packet it came from — into a single natural-language Spec.
• For the upstream layout (why-fronted), delegate to rules/format-upstream.md; for the integrated spec (requirements-crossing), delegate to rules/format-integrated.md; for the stakeholder one-pager (bottom line up front), delegate to rules/format-stakeholder-onepager.md; for the status report (bottom line up front), delegate to rules/format-status-report.md; for the decision memo (options × criteria comparison, verdict up front), delegate to rules/format-decision-memo.md. Express the middle format as a degree adjustment between the upstream / integrated rules, without adding another rule (the reader-specific presets are held as their own rules).
• Vary thickness by depth (DR111): the three shapes — upstream layout, integrated spec, and non-program layout — vary the thickness of each section according to the confirmed output depth (brief / standard / detailed) (per the "thickness by output depth" section of each format rule). Depth is an axis orthogonal to the shape and adds no new format. What thickens is the density with which the material is written down, not supplementing descriptions absent from the material to look thicker (INV73 = the Step 4 fabrication check is unchanged at every depth).
• Thickness-fixed reader presets (announce non-applicable shapes): the stakeholder one-pager, status report, and decision memo have, as the core of their shape, the very type that narrows the information for a specific reader, so the depth-based thickness change does not apply (thickness fixed). When a depth is specified for these, neither silently ignore nor silently apply it — announce in one line "this shape is thickness-fixed, so output depth does not apply," then generate per that shape's composition.
• When no format is specified (R2.4): use the default format and state explicitly in the output which format it was generated in (whether the default used was the upstream layout or the integrated spec). Do not pick the default silently.
• Reader-specific vocabulary opening: when the reader is judged a non-insider (a customer, executive, sales, or non-developer stakeholder who does not read code or .intent/ — the default for the one-pager format, or when the user specifies "customer-facing" etc.), follow rules/reader-vocabulary.md: paraphrase symbols (INV/DR) via the ledger and drop identifiers absent from the ledger (packet ids, skill names, etc.) from the body. For an insider reader, keep symbols as references for tracing, as before (derive the reader judgment from the existing source-scope interpretation; do not add a new state machine).

Step 4: Fabrication check (trace assignment / inferred marking / invariant preservation)

• Per rules/fabrication-guard.md, check whether the natural-language Spec assembled by the format mapping fabricates beyond the projection source.
• Trace each statement to a referenceable form pointing to its projection source (which Intent L-level / which compass section / which packet / which constraint) (R3.1). Mark statements with no grounding in the source as inferred and never mix them with the confirmed ones (R3.2). Hold the source's invariants / constraints without omission or alteration (R3.4). Present the supplemented (inferred) places as a list the user can review (R3.3; this is a warning and does not stop generation).

Step 5: Derived write (full replacement to .intent/nl-spec/, only the chosen output forms)

• Only after all reading, mapping, and checking are complete, last write the generated natural-language Spec to under .intent/nl-spec/ by full replacement, according to the output form confirmed in Step 1 (DR189) (rerunning with the same scope+format+form is idempotent by full replacement — R4.2). Write only the chosen forms (do not delete existing files of forms not chosen):
  • Markdown (default) → .intent/nl-spec/<format>.md (as before)
  • self-contained HTML → .intent/nl-spec/<format>.html. Make it a single file with the CSS embedded, referencing no external resources (CDN, external fonts, external images, external scripts) at all (applying INV2's zero external dependency to the output too). Bundle a single fixed color theme prioritizing readability (provisional; no swapping mechanism — DR189).
  • Marp slide Markdown → .intent/nl-spec/<format>.marp.md. Attach Marp frontmatter/directives and split into slides per the layout's section headings. The split is a transformation of placement, not a change in content (do not drop or add — Anti-539).
• Multiple forms are sibling projections of the same material, content-equivalent (INV100, Anti-539): when writing multiple forms at once, keep the confirmed content (the set of headings, requirements, acceptance criteria, inferred marks) equivalent across the forms. Do not add or drop content in only one form. Diagrams (the intent hierarchy map diagram, etc.) stay as code blocks in Markdown/Marp (the reader's environment renders them); in HTML, keep them in a readable form without embedding external JS.
• Do not call a rendering/conversion tool at runtime (generation is a file Write only — INV2). Leave rendering to the reader's browser (HTML) and the user's Marp environment (Marp).
• Treat this Spec internally as derived, regenerable, not the source of truth, and Git-untracked. However, do not output internal lifecycle boilerplate by default. Boilerplate such as “this document is not the canonical source,” statements about the source of truth, .intent/ paths, Git tracking, or derived-artifact status belongs in no output form. Include it only when the user explicitly requests internal lifecycle metadata, and then only in a non-customer-facing internal version. When actual inferred statements exist, retain their individual marks and the review list required by Step 4 independently of this boilerplate choice (R4.3).
• Never write to any canonical .intent/*.md (intent-tree / compass / packets), steering (tech.md), or application code (R4.1 / R4.4). Limit the write destination to under .

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/nl-spec/<format>.md (derived, regenerable, and Git-untracked are internal storage properties and are not written into the generated document). When an output form (DR189) is specified, co-produce only the chosen forms: Markdown=<format>.md (default) / self-contained HTML=<format>.html (a single file with CSS embedded, no external resources) / Marp slide=<format>.marp.md (split into slides by section heading, content-equivalent). When unspecified, Markdown only. Its content follows the confirmed target format:
  • Upstream layout: purpose (why) → invariants / constraints to hold → decision rules → individual demands → assumptions / unresolved (a separate inferred block, if any), in that order (per the composition in rules/format-upstream.md).
  • Integrated spec: overview → premise invariants / constraints → integrated demands with acceptance criteria → assumptions / unresolved (a separate inferred block, if any), in that order (per the composition in rules/format-integrated.md).
  • Stakeholder one-pager: bottom line (what is being built) → why we build it → what we won't do → where we are → assumptions / unresolved (if any), in that order. Bottom line up front (BLUF), and do not point internal identifiers (INV/DR/pkt-) at the reader bare (per the composition in rules/format-stakeholder-onepager.md).
  • Status report: three sections — what progressed → what got decided → what awaits a decision. Bottom line up front in each (per the composition in rules/format-status-report.md).
  • Decision memo: verdict (adopted / rejected, still-open marked explicitly) → options × criteria comparison → why the rejected options were rejected → revisit conditions → still open → assumptions / unconfirmed (if any), in that order. Verdict up front; never supplement evaluations or verdicts absent from the sources (cells without a record say "no record"; if the scope has no dilemma / decision material, do not generate; per the composition in rules/format-decision-memo.md).
  • Format default statement: when unspecified, state the default format used (Step 3; R2.4).
  • Depth statement: state at the top of the output which depth (brief / standard / detailed) it was generated in. When a depth was specified for a thickness-fixed reader preset (one-pager / status report / decision memo), also add that it "does not apply because the shape is thickness-fixed."
  • : assign each statement a reference to its projection source, and place statements with no grounding in the source as inferred, in a block / marking distinct from the confirmed ones.

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/nl-spec/. The canonical .intent/*.md (intent-tree / compass / packets / mode, etc.), steering (tech.md), and application code are read-only — never created, modified, or deleted there (the Write in the frontmatter is permitted solely for writing under .intent/nl-spec/. R4.1).
• Derived — not the source of truth: internally, the artifact is derived / regenerable and not the source of truth. Preserve this as a storage and update rule without exposing the lifecycle note in the generated document, and create no dual source of truth against canonical (R4.3).
• Fabrication suppression (the outward load-bearing problem): never leave a statement without a trace as confirmed (each statement is either traceable to a projection source or marked inferred). Never mix inferred with confirmed, and never omit or alter the source's invariants / constraints. Always present supplemented places as a review list and never dissolve them silently into the body (R3.x).
• Mapping ownership boundary: delegate the format mapping to this skill's rules/format-upstream.md / rules/format-integrated.md, and do not call map-cc-sdd.md. Do not change the behavior of /intent-export-cc-sdd (the source/format-fixed special case) (R5.3 / R5.5).
• Read-only: treat the projection sources (intent-tree / compass / packets / steering) read-only and do not create, modify, or delete them (R1.4).
• Zero external dependencies (INV2 / R5.1). Introduces no external package, AST parser, or custom schema; limited to Node standard and natural-language heuristics, completing the projection within a natural-language workflow.
• Does not modify application code (INV6 / R4.4).
• Naming / no external modification: follows the intent-* naming convention and does not modify external spec tools or the kiro-* development environment (R5.5).
• When prerequisites are absent: when the source scope is ambiguous or the corresponding artifact is absent, write nothing, state the absence/ambiguity, guide to the available scope or the missing artifact (the relevant skill to prepare it), and stop (fail-fast. R1.3).
• On partial gaps: layers / sections whose source material cannot be read are stated as "unfilled / unobserved" and omitted (never filled in by guessing).