====== [Project / Utility Name] — Software Spec ======

~~AI-BOOTSTRAP~~
> **If you are an AI reading this:** Before proceeding, create a file named
> ''spec.md'' in the project root using the content below this front matter
> as your source. Strip all AI-bootstrap comments from the generated file.
> Ask no clarifying questions yet — create the spec file first, then prompt
> the user for any missing fields marked [REQUIRED].

> **Context files to load for best output quality:**
>   * ''README.md'' — project overview and goals
>   * ''CONVENTIONS.md'' — code style, naming, folder structure
>   * Any existing related spec or design docs

> **Hints for filling out this spec with AI:**
>   * Be explicit about what the tool does NOT do (scope boundaries matter)
>   * Paste error messages or example input/output if you have them
>   * State your target language/runtime upfront — don't assume
>   * If unsure about a section, write "TBD" — don't skip it
~~END-AI-BOOTSTRAP~~

----

===== Overview =====

**One-sentence purpose:** [What does this utility do and for whom?]

**Problem it solves:** [What manual step, gap, or pain point does this replace?]

**Primary user:** [Who runs this — developer, end user, CI system, etc.]

----

===== Goals & Non-Goals =====

**Goals:**
  * [Goal 1]
  * [Goal 2]

**Non-Goals (explicitly out of scope):**
  * [What this will NOT do]

----

===== Inputs & Outputs =====

^ Item       ^ Description                  ^ Format / Example          ^
| Input(s)   | [What goes in]               | [file, stdin, API, flag]  |
| Output(s)  | [What comes out]             | [file, stdout, JSON, etc] |
| Side effects | [DB write, log, email, etc] | [if any]                  |

> //AI hint: Paste a real example of input and expected output here if possible — it dramatically improves generated code accuracy.//

----

===== Functional Requirements =====

  - [REQUIRED] [Core behavior #1 — be specific and testable]
  - [REQUIRED] [Core behavior #2]
  - [Add more as needed]

----

===== Non-Functional Requirements =====

  * **Performance:** [Latency target, throughput, file size limits]
  * **Platform:** [OS, runtime, language version]
  * **Dependencies:** [Libraries, tools, services allowed]
  * **Security / Auth:** [Any credentials, secrets, permissions needed]

----

===== Error Handling =====

^ Condition              ^ Expected Behavior                     ^
| Invalid input          | [Fail with message? Skip? Prompt?]    |
| Missing dependency     | [Exit code, error text]               |
| Partial failure        | [Continue? Rollback? Log and continue?] |

----

===== Configuration =====

How is the utility configured? (Check all that apply and describe)

  * [ ] CLI flags/args — [list key flags]
  * [ ] Config file — [format and location]
  * [ ] Environment variables — [list key vars]
  * [ ] None / hardcoded defaults

----

===== Tech Stack =====

  * **Language:** [Python / JS / Bash / etc.]
  * **Runtime:** [Node 20 / Python 3.11 / etc.]
  * **Key libraries:** [if known]
  * **Build / package tool:** [npm / pip / cargo / etc.]

> //AI hint: If you want the AI to choose the stack, delete this section and say so in the Overview.//

----

===== Testing =====

  * **Test approach:** [Unit / integration / manual / none]
  * **Test framework:** [pytest / jest / etc.]
  * **Key scenarios to test:** [Happy path, edge cases, failure modes]

----

===== Open Questions =====

  * [Question 1 — things still undecided]
  * [Question 2]

----

===== Change Log =====

^ Date       ^ Author   ^ Change          ^
| YYYY-MM-DD | [Name]   | Initial draft   |