Update Plan from User Responses

Process user responses in the questions document and update all related planning documents accordingly.

Prerequisites

• A plan created by the planning or planning-mode skills must already exist
• For default (non-ask) mode: the plan's questions document must contain at least one question with a non-empty ### Response section
• For ask mode: the plan's questions document must contain at least one unprocessed question (with or without a response)

Argument parsing

The skill takes a single optional argument:

• If the argument is the literal string ask (case-insensitive, trimmed) → enable ask mode and locate the plan via the Phase 1 strategies below (plan is not specified separately).
• If the argument is anything else → treat it as a plan name (existing behaviour).
• If the argument is empty → no mode flag and no plan name; fall through to the Phase 1 strategies.

ask is standalone — it cannot be combined with a plan name on the same invocation. If the user needs ask mode against a specific plan in a multi-plan repo, the Phase 1 multi-plan prompt will let them choose.

Throughout the rest of this skill, ask mode refers specifically to the case where the argument was ask.

Persistence

This skill belongs to the plans skill group. A persistence implementation decides where and how plans are stored. Before locating the plan, find the setting:

R="$(git rev-parse --show-toplevel 2>/dev/null)/.ai/config.properties"; { cat "$R" ~/.ai/config.properties | grep '^persistence\.plans[[:space:]]*=[[:space:]]*[^[:space:]]'; cat "$R" ~/.ai/config.properties | grep '^persistence[[:space:]]*=[[:space:]]*[^[:space:]]'; } 2>/dev/null | head -1 | tr -d ' \t\r'

• No output: use local-ai-folder-markdown, the default for this skill group
• persistence.plans={value} or persistence={value}: use {value}. If ../planning/persistence/{value}.md does not exist, tell the user the plans skill group has no {value} implementation and use local-ai-folder-markdown

Read ../planning/persistence/{implementation}.md and follow it whenever this skill lists or opens a plan, or reads, writes or updates a planning document.

Phase 1: Locate the plan

Resolve the target plan using the first matching strategy:

1. Context inference — check your conversation context for a plan location from a prior planning-mode/planning skill invocation in this session. If found, use it directly and confirm with the user (e.g. "Updating plan 2026-03-24 auth refactor — correct?"). Proceed on confirmation; if the user says no, fall through to the next strategy.
2. User argument — if the user provided a non-ask argument, resolve it as a plan name against the listed plans. (The ask keyword is a mode flag, not a plan name — see "Argument parsing" above.)
3. Single plan — if only one plan exists, select it automatically.
4. Multiple plans — list plans newest first in a numbered list and ask the user to choose.
5. No plans — tell the user no plans were found and suggest creating one with the planning-mode or planning skills.

Phase 2: Read all planning documents

Open the selected plan and read the following documents (skip any that don't exist):

1. questions
2. plan
3. findings
4. progress (if present)

If the questions document does not exist or contains no questions, tell the user there's nothing to process and stop.

Phase 3: Identify questions to handle

Scan the questions document for unprocessed questions, in document order. A question is "processed" when it carries the processed mark defined by the persistence implementation; processed questions are always skipped.

What counts as "to handle" depends on the mode:

• Default mode: only unprocessed questions with a non-empty ### Response section. If none exist, tell the user there is nothing to process and stop.
• Ask mode: every unprocessed question, whether or not it has a response yet. If no unprocessed questions exist at all, tell the user and stop.

Phase 4: Process responses and update documents

Iterate the unprocessed questions identified in Phase 3 in document order. For each question, follow the branch that matches the current state.

Branch A — Question has a non-empty ### Response

This is the standard processing path (applies to both default mode and ask mode):

1. Understand the response — determine what decision, clarification, or constraint the user provided
2. Assess impact on the plan — decide whether the plan document, the findings document, or the progress document need updating
3. Update planning documents — make targeted edits:
   • plan: update phases, decisions, key questions, or scope as needed
   • findings: record new requirements, technical decisions, or constraints derived from the response
   • progress (if it exists): log a new entry noting the questions processing session
4. Mark the question as processed — following the persistence implementation

Branch B — Question has an empty ### Response, ask mode is ON

Prompt the user interactively, then run Branch A:

1. Present the question verbatim — extract the full prose of the question body (everything between the ## Q[N]: ... heading and the ### Response heading), excluding HTML comments (<!-- ... -->) which are author-notes from the template, not part of the question itself. Pass this prose to the user without rephrasing.
2. Choose the prompt mechanism — if the question proposes a discrete set of options (heuristic — phrases like "Should we use X, Y, or Z?", "Pick one of: ...", explicit option lists), use the host agent's structured question tool:
   • Claude Code → AskUserQuestion
   • GitHub Copilot → askQuestions
   • Other agents → use their equivalent structured question tool if available
   • Otherwise (or for open-ended questions) → prompt the user in plain text
3. Capture the answer:
   • If the user provides an answer → write it verbatim into the questions document under the existing ### Response heading (do not rephrase, do not editorialise). Then run Branch A for this question (process the answer and mark the question as processed).
   • If the user skips/declines/answers with empty text → leave the ### Response empty, do not mark the question as processed, and move on to the next question.

Branch C — Question has an empty ### Response, ask mode is OFF

Skip the question silently and move on. It remains unprocessed and will be reported in Phase 6 as still-unanswered.

Rules (apply to all branches)

• Never modify the user's response text
• Preserve existing content in all documents except in the plan document; append or update, don't overwrite
• Replacing/removing/overwriting in the plan document is permitted
• If a response contradicts a prior decision, update the decision and note the change

Phase 5: Add follow-up questions

If processing the responses raises new questions or ambiguities:

1. Add new questions to the bottom of the questions document following the existing template format
2. Continue the existing numbering sequence (e.g. if last question was Q3, new questions start at Q4)
3. Reference the response that prompted the follow-up (e.g. "Follow-up from Q2")
4. Include an empty ### Response section below each new question

If no follow-up questions are needed, do not add any.

Phase 6: Report to the user

Provide a concise summary covering:

1. Responses processed — list which questions (by number and topic) were processed
2. Plan changes — state whether the plan was changed; if yes, briefly describe what changed and in which document(s)
3. New questions — if follow-up questions were added, explicitly tell the user:
   • That new questions are waiting in the questions document
   • List each new question inline (number and full question text)
   • Ask the user to review and respond to them
4. Still-unanswered questions — at the end of the report, list every unprocessed question whose ### Response is still empty (number and topic). This applies to all invocations of this skill, including default mode (where empty-response questions were skipped) and ask mode (where the user may have declined some questions). If every question has been answered or processed, omit this section.

If no changes were needed and no new questions arose, say so clearly.