spectra-ingest

name	spectra-ingest
description	Update an existing Spectra change from external context
effort	xhigh
license	MIT
compatibility	Requires spectra CLI.
metadata	{"author":"spectra","version":"1.0","generatedBy":"Spectra"}

Update an existing Spectra change — from a plan file or conversation context.

Plan file support is available when the tool has a plan directory (~/.claude/plans/). Otherwise, use conversation context to update artifacts.

Prerequisites: This skill requires the spectra CLI. If any spectra command fails with "command not found" or similar, report the error and STOP.

Input: Optionally specify a plan file path or name.

• /spectra-ingest ~/.claude/plans/agile-discovering-rocket.md
• /spectra-ingest agile-discovering-rocket
• /spectra-ingest (use conversation context or auto-detect plan file)

Steps

1. Locate the requirement source

   a. Argument provided → treat as plan file reference (prepend ~/.claude/plans/ and append .md if needed)

   • If the file exists → use it as the plan file source, proceed to Step 2
   • If the file does NOT exist → report the error and stop

   b. No argument, plan file detectable:

   • Check conversation context for plan file path (plan mode system messages include the path like ~/.claude/plans/<name>.md)
   • If found and the file exists → use the AskUserQuestion tool to ask:
     • Option 1: Use the plan file
     • Option 2: Use conversation context
   • If the user picks plan file → proceed to Step 2
   • If the user picks conversation context → skip Step 2, go to Step 3

   c. No argument, no plan file detectable:

   • Check ~/.claude/plans/ for recent files
   • If recent files exist → list 5 most recent with the AskUserQuestion tool, include "Use conversation context" as an additional option
   • If the user picks a file → proceed to Step 2
   • If the user picks conversation context → skip Step 2, go to Step 3

   d. Conversation context fallback (no plan files found at all):

   • Use conversation context to update artifacts
   • If conversation context is insufficient, use the AskUserQuestion tool to get more details
   • Warn: "No plan file found. Using conversation context."

2. Parse the plan structure (skip if using conversation context)

   Claude Code plan files typically contain:

   • Title (# ...) — the high-level goal
   • Context section — background, motivation, current state
   • Stages/Steps — numbered implementation stages with goals and file lists
   • Files involved — list of files to modify/create
   • Verification section — how to test the changes

   Extract:

   • plan_title: from the H1 heading
   • plan_context: from the Context section
   • plan_stages: each numbered stage with its goal and file list

---

Rationalization Table

What You're Thinking	What You Should Do
"The existing artifacts are close enough, just adjust the tasks"	Read the new context carefully. "Close enough" means you're missing something
"The proposal doesn't need updating, the change is the same"	If new context exists, the proposal likely needs updates. At minimum, check
"I can merge these tasks, they're basically the same"	Keep tasks granular. Merged tasks are harder to track
"The completed tasks still apply, no need to review"	Verify they're still relevant to updated scope. Don't blindly keep stale work
"This spec change is minor, skip the scenario update"	If the requirement changed, the scenario must change
"The conversation didn't discuss this artifact, so skip it"	Absence of discussion doesn't mean absence of impact. Check

---

7. Analyze-Fix Loop (max 2 iterations)

   spectra analyze <name> --json
   

   1. Filter findings to Critical and Warning only (ignore Suggestion)
   2. If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed
   3. If Critical/Warning findings exist: a. Show: "Found N issue(s), fixing... (attempt M/2)" b. Fix each finding in the affected artifact c. Re-run spectra analyze <name> --json d. Repeat up to 2 total iterations
   4. After 2 attempts, if findings remain:
      • Show remaining findings as a summary
      • Proceed normally (do NOT block)

8. Validation

   spectra validate "<name>"
   

   If validation fails, fix errors and re-validate.

9. Summary and next steps

   Show:

   • Source used: plan file (<path>) or conversation context
   • Change name and location
   • Artifacts created/updated
   • Validation result

   Use AskUserQuestion tool to confirm the workflow is complete. This ensures the workflow stops even when auto-accept is enabled. Provide exactly these options:

   • First option (will be auto-selected): "Done" — End the ingest workflow. Inform the user they can run /spectra-apply <change-name> when ready.
   • Second option: "Apply" — Invoke /spectra-apply <change-name> to start implementation.

   If AskUserQuestion tool is not available, display the summary and inform the user to run /spectra-apply <change-name> when ready. Then STOP — do not continue.

   After the user responds, if they chose "Done", the workflow is OVER. If they chose "Apply", invoke /spectra-apply <change-name> to begin implementation.

Guardrails

• NEVER modify the original plan file in ~/.claude/plans/
• NEVER write application code — this skill only creates/updates Spectra artifacts
• NEVER create new changes — ingest only updates existing changes. If no active change exists, direct user to /spectra-propose
• When updating existing changes, preserve all completed tasks ([x]) — never revert progress
• If the source content is too brief to fill all artifact sections, use the AskUserQuestion tool to get more details rather than inventing content
• If spectra CLI is not available, report the error and stop
• Verify each artifact file exists after writing before proceeding to next
• NEVER skip the artifact workflow to write code directly
• If AskUserQuestion tool is not available, ask the same questions as plain text and wait for the user's response