Skip to content

/steer:spec intake

Absorb a Product Owner's spec or roadmap document - and every later version of it - into the /spec spine, surfacing exactly what changed each time. A mode of /steer:spec; the intake skill behind it is internal and is not typed on its own.

When to use

Use when a PO hands over a new or updated office document (a spec in Word, a roadmap deck, a requirements spreadsheet, a PDF) and you need to detect what changed versus the last version and fold the real changes into /spec and the tracker - without losing human-authored content. Reach for it whenever a re-sent document arrives with no pointer to what was edited.

Argument hint: [<path-to-doc> | clarify <path-to-doc> | <source-id> | status]

The problem it solves

Office documents are opaque binaries: git can't diff them and Claude can't read them directly, so a re-sent file is a blob with no indication of what moved. /steer:spec intake commits, for every version, both the original binary and a normalized Markdown extraction - so a plain git diff of successive extractions is the "what changed" the PO never spells out.

What it does

  1. Identity - resolves a stable kebab-case source-id for the logical document, decoupled from the filename (a renamed re-send still maps to the same source).
  2. Version, convert, commit - lays down spec/sources/<source-id>/versions/<vNNNN-DATE>/ holding original.<ext> (provenance) and extracted.md (the diff surface), and commits both together. The dropped file is relocated into that canonical home (a history-preserving git mv for an in-repo drop - the same move /steer:work tidy performs), not copied, so it does not stay stalled where the PO uploaded it; a file outside the repo is copied in and left in place. Conversion walks a ladder: the repo's mise run convert:doc <file> task (the deterministic, committable path), then a native Read for a text-bearing PDF, then a manual floor. There is no markitdown MCP server - it was retired in favour of that on-demand task.
  3. Diff - git diffs the new extraction against the prior version and groups the hunks into change units by heading anchor (topic, not line number).
  4. Report - prints a structured what-changed table.
  5. Reconcile - routes each change through the skill that owns the artifact (/steer:spec-scaffold, /steer:spec, /steer:audit, /steer:spec roadmap, /steer:spec questions), never clobbering human prose: conflicts become Open questions, drift is surfaced for a human, and the run writes one spec/history/ entry file summarizing the version - absorbing a source document is one notable event, not one per absorbed change.

Clarify mode takes a different middle: a client clarification document is not a version of a prior spec, so instead of the diff (steps 3-4) it segments the extraction semantically, maps each unit inline against open questions and the feature list, and sorts them into a three-bucket, human-confirmed worklist - answers -> /steer:spec questions, new scope -> the reconcile rows, unmatched -> surfaced for the human (never guessed). The shared front-end (identity, versioned commit, action-history record) is unchanged.

Modes

Mode What it does
/steer:spec intake <path-to-doc> Absorb the supplied document - the normal "the PO just sent a new version" path.
/steer:spec intake clarify <path-to-doc> Absorb a client clarification document that answers open questions and/or adds scope: segment -> map to the spine -> three-bucket worklist (answers to /steer:spec questions, new scope to the reconcile rows, unmatched surfaced). Every folded answer records the source-ref + quoted span. The document a PO fills in is usually the outbound questionnaire /steer:spec questions bundle produces - when it carries [<feature-id>] Q-NNN answer headings, clarify segments per heading and maps each answer to its question by that feature-scoped key deterministically. Not /steer:spec clarify <feature-id>, which interrogates a draft rather than absorbing an answers document.
/steer:spec intake <source-id> Absorb the newest unabsorbed version of an already-tracked source, by its id - no path needed.
/steer:spec intake (no argument) List the sources under spec/sources/ and ask which document to absorb.
/steer:spec intake status Read-only ledger: each source, its latest absorbed version, mapped features/issues, and any version still awaiting a text-bearing copy.

Idempotency

Re-running on an unchanged document is a no-op - a binary-hash guard detects an identical file (even re-sent under a new name). A genuinely new version diffs only against the current latest, so the report is always the incremental delta. If the byte-identical re-send is sitting at an in-repo drop location, intake surfaces it as a redundant duplicate of the already-absorbed source and routes it to /steer:work tidy (which removes an absorbed duplicate on a yes) rather than leaving it stalled.

Where it fits

spec/sources/ is the versioned home for recurring PO documents, alongside spec/design/ (UI exports plus the living architecture diagram) and spec/reference/ (one-off prose). A document sent once can stay loose under spec/reference/; the moment it starts arriving in versions, it belongs under spec/sources/. See the convert:doc task for the converter, and /steer:reference design-sources for the shared provenance model.