1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: CC0-1.0
 5-->
 6
 7# How to Write a Technical Specification
 8
 9## Pre-requisites
10
11Before you start, read the `Vibe Flow Guide.md` entirely.
12
13You need:
14
15- the TASK_DIR - if you don't have it, ask the user for a **ticket ID**
16- the current CYCLE_LETTER and the next FILE_NUMBER - deduce them by yourself - by default, start with a new cycle (bump the CYCLE_LETTER, reset the FILE_NUMBER to 1)
17
18## Phases
19
20When the user asks you for a SPEC (technical specification), you MUST follow this process:
21
221. **Investigation Phase**: Research the codebase to understand the current implementation and identify the problem
232. **Discussion Phase**: Collaborate with the user to explore the problem space and potential solutions BEFORE writing the specification file
243. **Specification Phase**: Only after user approval, write the final specification file
25
26The discussion phase is MANDATORY. Remember that you are a newcomer to this project while the user has extensive experience with the codebase and will be happy to help guide you.
27
28## Discussion Format
29
30Engage in a thorough collaborative discussion covering:
31
32- **Problem exploration**: Present your understanding of the problem and ask clarifying questions
33- **Current implementation analysis**: Share what you discovered and ask for confirmation or corrections
34- **Multiple solution approaches**: Present several viable alternatives when they exist, explaining trade-offs
35- **Sub-subject identification**: Break down the problem into all relevant sub-components and ensure each is addressed
36- **Design decisions**: Ask for user input on key architectural choices
37- **Edge cases and implications**: Explore potential issues and broader system impacts
38
39You should ask questions freely to ensure you fully understand:
40
41- The problem context and requirements
42- Existing patterns and conventions in the codebase
43- User preferences for implementation approaches
44- Any constraints or considerations you might have missed
45
46## Specification File Guidelines
47
48After the user approves your proposal, write the specification in a markdown file in TASK_DIR. Compose the filename with the current CYCLE_LETTER and the next FILE_NUMBER, e.g. `A1-spec.md`. Do not overwrite an existing file.
49
50- Usually a specification is around 40~60 lines
51- **Do not add backward compatibility** unless explicitly requested. Prefer clean code. Unused code must be removed.
52- A specification is not always immediately executed, and you have to assume that the code can change before it is executed. You can mention a function by name, but NEVER mention specific line numbers as they will become obsolete
53- Do not include any detailed code in the specification. Instead, refer to the relevant source files by their paths or function names
54- Assume that the specification will be read by developers familiar with the codebase
55- Do not include sections like "Benefits", "Code Style Compliance" or anything that adds no new information. Focus on the problem and the solution