How do you refine a spec after having generated plan and/or tasks?

[bendavis78]

I've been fumbling around with this workflow trying to understand what I'm supposed to do after /analyze when I realize something in the original plan was off and needs to be adjusted. When I run /spec to udpate the spec, the LLM get s confused thinking it's supposed to create a new feature branch. So, I just tell the LLM to update the spec.md directly w/o the slash command. When I update the spec, I need to update the plan, so I run /plan and it seems to blow away the old plan, removing any manual changes I had made.

So, what's the process for refining spec, plan, tasks, etc after running /anaylize? Am I expected to start over when something was off during the spec phase?

[saarsa]

The best way is simply to ask him to make the file changes according to your preferences.
The files are live you can modify them yourself or ask the LLM to do it for you.

Don’t forget that later you can do vibe coding at the end for the finishing touches, and even ask the LLM to add your requirements to the spec.md file since spec.md is the base file or to any other file.

I also recommend watching this video of the creator of spect-kit:
https://youtu.be/SGHIQTsPzuY?si=-pqrJcdsQ4iMhVU0

And the creator’s channel:
https://youtube.com/@dendev?si=CztJpA-8Nw4qCNak

[bendavis78]

Thanks! I've watched those videos. I guess what I'm really asking is, are the slash commands designed to only be run once? Should I only run them when I want to start over from a certain phase? That might be something good to put in the docs.

[smackesey]

I am also very confused by this, especially since the description for speckit.specify is:

description: Create or update the feature specification from a natural language feature description.

It SAYS "or update", but /speckit.specify seems to always want to run the "create-new-feature" script-- also the content claims that the user input IS the feature description, which is not true for an update.

FWIW, this worked for me:

/speckit.specify Update the spec, taking into account the new template. Because we are updating the existing spec, the existing spec.md (found in the /specs dir) for this branch should be taken into account, and you should also skip the create-new-feature.sh script

[saarsa]

Look, at the end of the day, an LLM is like a servant it does whatever you tell it to do, and everything depends on your words and how well you explain yourself.

The command /speckit.specify
is basically an instruction manual for what to do. I didn’t see any explanation there on how to specifically update the file
it just adds various bits of context, some of which can be problematic and some of which can actually help you.

You have four ways to work with the LLM:

You can just talk to it directly.
If you continue the conversation that started with /speckit.specify, it will work like magic.
That’s why it’s worth starting a new chat after /speckit.specify if the code agent saves the previous conversations.

in new chat you can also talk to it normally and ask it to make changes.
This can sometimes not work perfectly.

You can reload the command /speckit.specify,
but you have to explicitly tell the LLM not to run the script
scripts/bash/create-new-feature.sh --json "{ARGS}"
or ps, depending on which environment you’re developing in.
That can also sometimes fail.

Or you can just add this part which is the part about how to handle the file from within specify.md:

## General Guidelines

## Quick Guidelines

- Focus on **WHAT** users need and **WHY**.
- Avoid HOW to implement (no tech stack, APIs, code structure).
- Written for business stakeholders, not developers.
- DO NOT create any checklists that are embedded in the spec. That will be a separate command.

### Section Requirements

- **Mandatory sections**: Must be completed for every feature
- **Optional sections**: Include only when relevant to the feature
- When a section doesn't apply, remove it entirely (don't leave as "N/A")

### For AI Generation

When creating this spec from a user prompt:

1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
2. **Document assumptions**: Record reasonable defaults in the Assumptions section
3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
   - Significantly impact feature scope or user experience
   - Have multiple reasonable interpretations with different implications
   - Lack any reasonable default
4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
6. **Common areas needing clarification** (only if no reasonable default exists):
   - Feature scope and boundaries (include/exclude specific use cases)
   - User types and permissions (if multiple conflicting interpretations possible)
   - Security/compliance requirements (when legally/financially significant)
   
**Examples of reasonable defaults** (don't ask about these):

- Data retention: Industry-standard practices for the domain
- Performance targets: Standard web/mobile app expectations unless specified
- Error handling: User-friendly messages with appropriate fallbacks
- Authentication method: Standard session-based or OAuth2 for web apps
- Integration patterns: RESTful APIs unless specified otherwise

### Success Criteria Guidelines

Success criteria must be:

1. **Measurable**: Include specific metrics (time, percentage, count, rate)
2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
3. **User-focused**: Describe outcomes from user/business perspective, not system internals
4. **Verifiable**: Can be tested/validated without knowing implementation details

**Good examples**:

- "Users can complete checkout in under 3 minutes"
- "System supports 10,000 concurrent users"
- "95% of searches return results in under 1 second"
- "Task completion rate improves by 40%"

**Bad examples** (implementation-focused):

- "API response time is under 200ms" (too technical, use "Users see results instantly")
- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
- "React components render efficiently" (framework-specific)
- "Redis cache hit rate above 80%" (technology-specific)

[Hieropold]

I'm using /speckit.clarify for this and just add whatever needs to be changed. It works as far as I can see, but I'm not sure if I'm using this as it was supposed to be done 😅

[thawkins]

I have been putting feature requests and bugs in the GitHub issues on my repo, and then telling the system to look there for new features or bugs and resolve them. It puts the analysis info into a comment on the issue, and then works on each issue until it thinks it has fixed it, it then asks me to test and close. I'm looking at using Milestones to group them for releases, but have not tested that yet.

It allows you to switch context quickly if needed.

[brooke-hamilton]

The /speckit.analyze command outputs a grid called the "Findings Table". Each row has an identifier like "A1, C2", etc. After looking at the table and deciding which ones to fix, just prompt with something like "Fix A1, C2" and the LLM will use the previous context to understand what to fix.

This isn't specifically called out in the documentation, and I had the same confusion, but this works well for me so far.

Generally, after running any of the Spec Kit commands, you can further refine things with regular LLM prompts.

[aytugdolek]

Drop the new branch and start over.