Skill: spec-refine — iterate spec from Q&A, comments, and new questions

[ifireball]

What happens: After spec-start produces initial spec and Q&A files, there is no standard skill for folding follow-up input back into the spec.

What should happen: A spec-refine skill guides updating the spec using answers recorded in the Q&A file, material from a dedicated comments file, and appending any newly surfaced questions back to the Q&A file.

Context: Sub-issue of #797. Depends on #801 (spec-start) for the initial artifact shape and workflow.

[fullsend-ai-triage]

Meeting update — 2026-05-13

Relevant to this issue: The team discussed an experiment combining the Analyze CLI with a refinement agent and refine outcome skill, which aligns with the spec-refine workflow.

• An experiment PR will be created detailing the Analyze CLI integration, refinement agent, and refine outcome skill
• A demo of the Analyze integration flow is being built for presentation to the feature refinement group

Related PRs: #875 — docs(skills): restructure spec-start qna.md as flat Q-NN log

Next steps: Publish the experiment PR and present the demo.

Meeting notes

[ifireball]

Suggested design for the spec-refine process:

The process deals with files in a given existing planning files directory such as docs/plans/yyyy-mm-dd-foo-bar/. Given file names are assumed to relative to that directory. The process should start with discerning the directory to work on from the context, if it remains unclear the process should stop and raise an error.

Phase 1 - comment handling

If there is a comments.md file assume it may have multiple comments in it and would be formatted like the following (The following text is merely an example but it shows the kinds of things that may appear in the comments file)):

# Comments (optional heading)

## General comment one - @optional-attrbution

General comment text 

## General comment with inline context - @other-attribution

In section  XXX of the spec there is a concern....

## For question Q-03

Some question response or further inquiry text

## For file `spec.md` lines 30

The line says ... but should say ...

Read the comments file. Then, for all the comments that refer to locations in the qna.md file (as defined by the spec-start skill), try to include them as answers to the questions in the file. Used the defined format for including answers. Answers may be added as follow up for question that may already have answers to them. Add answers to the end of the answers list for the question, later answers in the comments file should appear as later answers for the question. A comment may include text that answers several questions, if so, place answers to all the relevant questions. Remove any text that you have managed to include as answers to questions from the comment file. If you manage to handle all the text for a comment - remove the whole comment section.

For any remaining comments in the comments file, try to incorporate what it suggests to the spec.md file or the qna.md file as appropriate, you may add new questions to qna.md to request further clarifications for issues as needed. Since dealing with a comment might require some complex processing, conducting research in the the code in the repository or performing web searches, we should aim to set things up so that each comment or topic is dealt with by a different sub-agent. Comments may respond to one another in which case they should be dealt with together. It can be assumed that later comments override earlier ones.

(to be continued with the QnA handling phase)

[ifireball]

(Continue design)

Phase 2 - QnA handling

For each question in the qna.md file consider the answers for it. If it is fully answered, incorporate the answers back into the spec.md file. If the given answers had raised further questions or left open issues to be discussed, add your own answer that provides any information you can to help the users make the needed decisions and raises the issues that still need to be decided upon. If the discussion on a question at least partially answers it, include the information back in spec.md.

Since dealing with the discussion on any particular question might require a significant amount of processing or research, we should aim to make it happen in its own sub-agent.

Phase 3 - review

Self-Review the spec, make sure that implementation options that were overruled are removed, make sure the file is self-consistent, make sure it is brief, does not include unnecessary repetitions but make sure not to omit any design details and decisions provided by the users. Apply all the self-review criteria that is mentioned in spec-start.