Up & Running with GitHub Spec Kit #3 - The /specify Command

Summary

This video walks through the process of using the 'specify' command to create a high-level specification for a new feature in an app. The speaker explains how to break down a large project into smaller features for better clarity and execution. Emphasis is placed on focusing on the 'what' and 'why' of the feature, rather than the technical 'how'. The session demonstrates the creation of a goal-tracking app spec, from branching to the specification document generation, highlighting key aspects such as user stories, acceptance criteria, functional requirements, and entity definitions. The speaker also hints at using the 'clarify' command for further refinement in future lessons.

Takeaways

• 📝 The `constitution` command updates the constitution file, establishing guiding principles for creating new specs or plans.
• ⚡ The `specify` command is used to create high-level specifications for new features or segments of an application.
• 🎯 Focusing on smaller, contained features is more effective than attempting a full app spec in one step.
• 💡 Specs should emphasize the 'what' and 'why' (user experience and goals) rather than technical implementation details.
• 📁 The `create new feature` script creates a new branch, folder, and spec file for the feature, keeping work separate from the main branch.
• 🔖 Branch names are generated using the feature number and the first three words of the user input for clarity and organization.
• 📊 The spec file contains metadata, execution flow instructions, user stories, acceptance scenarios, edge cases, functional requirements, key entities, and content quality checklists.
• ✅ Acceptance scenarios outline expected user interactions and behaviors on the app, ensuring alignment with user needs.
• ❓ Edge cases highlight questions that require clarification, which can be addressed using the optional `clarify` command.
• 🎨 The spec emphasizes user value, business needs, and a visually appealing interface without diving into implementation details.
• 🔄 Functional requirements (FRs) provide a detailed list of actions the system must support to meet the feature's goals.
• 📌 Key entities like 'Goal' and 'User Session' define the main data models for the application.
• 🛠️ Checklists ensure all mandatory sections are complete, requirements are testable, and content maintains quality for non-technical stakeholders.

Q & A

What is the purpose of using the 'specify' command?

The 'specify' command is used to create a high-level specification for a new feature or segment of an application, focusing on the what and why rather than the how. It helps to structure the feature before diving into technical implementation.

Why does the speaker prefer to work on smaller, contained features instead of large, one-shot specs?

The speaker believes that working on smaller, contained features reduces the risk of the models veering off track. This approach provides more manageable chunks of work, allowing for better focus and clarity. Although larger specs can work, smaller features are considered more practical in practice.

What does the specification prompt contain after running the 'specify' command?

After running the 'specify' command, the specification prompt creates a new feature branch, generates a new folder for the spec file, and populates the spec with a high-level description based on the user input. It also includes execution instructions for the agent, metadata, user stories, acceptance scenarios, functional requirements, and other elements.

What is the role of the feature branch created in the specification process?

The feature branch separates the new spec work from the main branch, ensuring that the new feature is developed in isolation. This allows for focused development and avoids directly modifying the main branch, maintaining the stability of the core codebase.

What are 'acceptance scenarios' in the context of this spec creation process?

Acceptance scenarios are predefined conditions that describe how a user will interact with the app. They outline expected behavior and functionality, such as displaying columns for current and completed goals. These scenarios help to ensure that the spec aligns with user needs and expectations.

What are functional requirements (FRs) in a spec file?

Functional requirements (FRs) specify the necessary functionality of the system, such as displaying goal titles, calculating days remaining, and showing checkboxes. These FRs describe what the system must do in order to meet the user's needs as described in the spec.

Why does the spec include 'edge cases'?

Edge cases are included to identify potential scenarios that may not be covered by standard functional requirements. These cases highlight exceptions or unusual behavior that may require clarification or special handling during implementation.

What is the significance of 'needs clarification' tokens in the spec file?

The 'needs clarification' tokens indicate areas where the user input is unclear or lacks enough detail for implementation. These tokens signal that additional clarification is needed before development can proceed smoothly.

What is the purpose of the 'clarify' command in this process?

The 'clarify' command is used to resolve any uncertainties or incomplete sections marked with 'needs clarification' tokens. This command helps refine the spec by seeking additional information, ensuring the feature is fully defined before implementation.

How does the spec ensure that it stays at a high level and does not dive into technical details?

The spec follows guidelines to focus on the 'what' and 'why' rather than the 'how.' This means the specification does not detail specific technologies or architectures but instead describes the user experience, goals, and functionality at a conceptual level, leaving implementation details to be addressed later.