Add some attribute to denote the order that the plan, specify & tasks prompts should be used

[czer323]

I am not smart man. I find myself never quite knowing - which prompt is the correct prompt to use first. And since the prompts don't have any validations for checking if prior prompts have already been ran, I am encountering complications.

I specifically have trouble determining the difference between specify and plan. Am I planning to create specs? Or generating specs to make plans? Hope that context helps to make sense of my new user confusion.

For the sake of trying to make up for my moronism, I've tried to some extra research for you. Kind of a long read, but I found entertainment in it.

User Story

As a New User
I want some way to know the correct order to run prompts
So that I do not do dumb things.

Possible solutions

• Add some numerical value to the prompt name
  • Example
    • Specify_01.prompt.md
    • Plan_02.prompt.md
    • Tasks_03.prompt.md
• Change the terminology between Specify and Plan -
• Add language for the LLM to confirm that the files exist first. If they don't, halt or start that prompt instead.
• Add a readme to the .specify folder with instructions for the correct sequence. Something that can be easily referenced. It's on the github, so that's a thing I can look at now, but in the folder would be great too. I personally use VSCode, so it'd be easy to check.
• Add an additional prompt that provides the sequence? Seem like a waste of tokens though.

Funsies - Part 1

So, I asked Gemini what it thought the correct sequence was.

Prompt:

Imagine you are a new user to a software development team, and there is a tool you can use to help plan for future features of a development project.

You have three options you can run to start generating the plans, but they must be ran in sequence.

Here are the three terms you can choose:

• Plan
• Specify
• Tasks

Which order do you think they should be ran to successfully generate a detailed set of files to implement the feature?

The files generated will be:

• data-model.md
• contracts/
• quickstart.md
• research.md
• spec.md
• tasks.md

---

The model proceed to give me a few different sequence, so I provided this prompt:

Prompt:

For each of the 3 sequences you provided, provide a score from 1 to 10 that represents the most likely sequence.

Gemini Flash 2.5 Thinking Response:

Okay, let's score these sequences based on how likely they are to successfully generate a detailed set of files to implement the feature for a new user aiming for comprehensive planning.

---

1. Plan -> Specify -> Tasks (PST)

• Score: 9/10

• Justification: This is the most logical and commonly recommended sequence for a new user looking to generate a comprehensive and detailed plan.

  • Plan: Starts with the big picture, defining the "why" and "what" at a high level. This naturally leads to research.md and initial scope setting.
  • Specify: Builds upon the plan to define the technical "how." This is where the bulk of the detailed design documents like data-model.md, contracts/, and the in-depth spec.md would be generated, ensuring they are aligned with the overall plan.
  • Tasks: With a clear and detailed specification, breaking down the work into tasks.md and creating a quickstart.md becomes straightforward and accurate.
  • Likelihood of Success: High. It minimizes rework by ensuring a solid foundation before diving into implementation details or task breakdown. For a new user, this structured approach provides a clear path and reduces ambiguity.

---

2. Specify -> Plan -> Tasks (SPT)

• Score: 6/10

• Justification: While plausible in specific contexts, this sequence is less likely to produce a holistically successful detailed plan for a new feature initially.

  • Specify: Starting here implies a very clear understanding of the technical details (data-model.md, contracts/, spec.md) upfront, perhaps for a well-defined component or an integration with known interfaces. However, for a new feature, this risks defining the "how" before fully understanding the "why" or "what problem we're solving."
  • Plan: Trying to "plan" after specifying can lead to discovering that the initial specification doesn't fully align with strategic goals or user needs, requiring rework on the initial specification. This is where research.md might be generated but could invalidate some of the prior "Specify" output.
  • Tasks: The tasks might be based on a potentially misaligned or incomplete specification, or they might be refined after the planning phase, adding overhead. tasks.md and quickstart.md are generated last.
  • Likelihood of Success: Moderate. It can work if the initial "Specify" is extremely well-informed by prior tacit knowledge, but for a new user, it carries a higher risk of misalignment and subsequent rework, making it less "likely" to be seamlessly successful for a detailed set of files without iteration.

---

3. Plan -> Tasks -> Specify (PTS)

• Score: 4/10

• Justification: This sequence leans heavily towards rapid iteration or prototyping, which is often at odds with generating a detailed set of files before implementation, or ensuring that those files are fully comprehensive from the outset.

  • Plan: Starts well with high-level understanding (research.md, initial high-level spec.md).
  • Tasks: Jumping directly to tasks.md and quickstart.md implies starting implementation or prototyping based on a less detailed specification. The idea is often to learn by doing.
  • Specify: The detailed data-model.md, contracts/, and the full spec.md would likely be generated after some of the "tasks" have been completed and lessons learned. This means the initial "tasks" were not based on a fully detailed specification, and the "detailed set of files" might only become truly robust after the initial implementation.
  • Likelihood of Success: Low for generating a detailed set of files to implement the feature before development. While effective for agile development or exploration, it usually means the "detailed files" (especially the specification, data model, and contracts) are emergent rather than prescriptive at the start. For a new user specifically tasked with planning and generating a detailed set of files upfront, this sequence is less direct and more prone to requiring significant updates to those detailed files post-task execution.

For Funsies - Part Deux:

After I provided it access to the github to review the actual sequence, I asked it to write a user story and brainstorm potential solutions.

Gemini Flash 2.5 User Story:

Here is a user story addressing the confusion around the Specify, Plan, Tasks sequence for github/spec-kit, framed as if for submission to GitHub:

---

User Story 1: Clear Workflow Guidance

As a new user to github/spec-kit,
I want to easily understand the recommended sequence of Specify, Plan, and Tasks and why it's structured that way,
So that I can confidently follow the correct workflow, generate my feature files efficiently, and avoid initial confusion or incorrect usage.

Acceptance Criteria:

• Onboarding Tour: Upon first interaction (e.g., initial spec-kit init or accessing the spec-kit documentation), there is a brief, interactive tour or a prominent "Getting Started" guide explaining the SPT sequence.
• Quick Reference: The core README.md and command-line help (spec-kit --help) clearly state the recommended Specify -> Plan -> Tasks flow with a brief rationale.
• Diagram/Visual Aid: A simple diagram or flowchart is provided in the documentation illustrating the progression through the three stages and their expected outputs.
• Tool Tip/First Run Messaging: When a user attempts to run a command like spec-kit plan or spec-kit tasks without having completed an initial spec-kit specify step, a helpful message is displayed suggesting the correct preceding action.

Hi Me again...

So, let's pretend I wrote that. ;) Yeah, that was me. Pinky promise.

Final funsie,

Prompt

Imagine that the only solution was to somehow change the terminology. You currently have specify - which clearly aligns with the branding for the project, and you have plan.

What terms would be suited to be used, to allow the user to better align their intent with the correct prompt name? Try to provide a confidence score for each suggested sequence from 1 to 10.

Gemini Flash 2.5 Thinking Response:

Given the constraint to retain "Specify" due to branding and focusing on changing terminology to better align user intent with the correct sequence (Specify -> [New Term 1] -> [New Term 2]), the primary confusion point is the term "Plan" in its second position.

Here are a few suggested sequences with alternative terminology, along with confidence scores:

---

1. Sequence: Specify, Design, Tasks

• Confidence Score: 9.5/10
• Rationale:
  • Specify: Clearly defines the what and why of the feature, creating the detailed specification.
  • Design: This term strongly implies the technical architecture and solutioning that follows a detailed product specification and precedes the breakdown into implementation tasks. It clearly distinguishes this stage from a high-level "plan" that might traditionally come first. This aligns perfectly with defining the how from a technical perspective (tech stack, architecture, etc.).
  • Tasks: Remains clear for the list of implementation steps that are derived from the technical design.
• Why it's good: "Design" is a widely understood term in software development for the technical elaboration phase. It creates a natural and intuitive flow from product definition to technical solution to actionable steps.

---

2. Sequence: Specify, Architect, Tasks

• Confidence Score: 9/10
• Rationale:
  • Specify: As above, defines the product.
  • Architect: Similar to "Design," "Architect" precisely describes the technical structuring and decision-making phase that takes a specification and outlines its technical implementation. It directly reflects the creation of architectural diagrams, component choices, and system layout.
  • Tasks: Remains clear for the list of implementation steps.
• Why it's good: "Architect" is a very strong and precise term for the technical definition stage. The slight reduction in confidence compared to "Design" is only because "Design" is perhaps a more universally applied term for this type of activity, whereas "Architect" can sometimes imply a higher-level, more abstract role than the detailed technical solutioning that occurs here.

---

3. Sequence: Specify, Solution, Tasks

• Confidence Score: 8.5/10
• Rationale:
  • Specify: As above, defines the product.
  • Solution: As a verb, "solution" (e.g., "solution the spec") implies devising and detailing the technical answer to the requirements laid out in the specification. It clearly indicates this phase is about crafting the technical solution.
  • Tasks: Remains clear for the list of implementation steps.
• Why it's good: "Solution" is concise and directly conveys that this step is where the technical problems are addressed and answers are formulated. The reason for a slightly lower confidence score is that "Solution" as a direct command verb might feel a bit more abstract or less active compared to "Design" or "Architect" for some users, but its intent is clear.

[github-actions]

This issue has been automatically marked as stale because it has not had any activity for 150 days. It will be closed in 30 days if no further activity occurs.

[github-actions]

This issue has been automatically closed due to inactivity (180 days total). If you believe this issue is still relevant, please reopen it or create a new issue.