Project Specification Writer (Instruction-only)

Goal

When invoked, produce a single, comprehensive specification document for the current repository/project with all required sections:

1. Architecture and technology choices
2. Data model
3. Key processes
4. Pseudocode
5. System context diagram
6. Container/deployment overview
7. Module relationship diagram (Backend / Frontend)
8. Sequence diagram
9. ER diagram
10. Class diagram (key backend classes)
11. Flowchart
12. State diagram

Default output file:

docs/specification.md

(If

docs/

does not exist, create it. If user requests another path, follow it.)

---

Invocation behavior

Minimal questions policy

Ask at most 5 clarifying questions only if the repo does not contain enough information to avoid unsafe guessing.
If information is missing, proceed with best-effort inference and add an “Assumptions & Open Questions” section near the top.

No hallucinations rule

Do not invent details. If you cannot locate evidence in the repo, label as:

• Assumption
• Unknown/TBD
• Open question

---

Repo reconnaissance workflow (do this first)

1. Identify repo root and high-level structure:
   • Look for:

     README*

     ,

     docs/

     ,

     architecture/

     ,

     ADR*

     ,

     design*

     ,

     SPEC*

     .
2. Detect tech stack and runtime:
   • Backend signals:

     pyproject.toml

     ,

     requirements.txt

     ,

     go.mod

     ,

     pom.xml

     ,

     build.gradle

     ,

     .csproj

     ,

     package.json

     (server),

     Dockerfile

   • Frontend signals:

     package.json

     ,

     pnpm-lock.yaml

     ,

     yarn.lock

     ,

     vite.config.*

     ,

     next.config.*

3. Detect data layer:
   • DB migrations:

     migrations/

     ,

     prisma/schema.prisma

     ,

     alembic/

     ,

     db/schema.sql

     ,

     knexfile.*

   • ORM models:

     models/

     ,

     entities/

     ,

     schema/

4. Detect deployment:

   • docker-compose.yml

     ,

     Dockerfile*

     ,

     k8s/

     ,

     helm/

     ,

     .github/workflows/*

     ,

     terraform/

5. Collect “evidence pointers” while reading (file paths + brief notes).
   You will use these pointers throughout the spec.

---

Output requirements (strict)

• Produce one Markdown document.
• Use clear headings matching the 12 required items.
• All diagrams must be in fenced Mermaid blocks:
  ```mermaid
  ...
  ```
• Each section must be project-specific (grounded in repo findings).
• Keep diagrams at the right abstraction level:
  • Context/Container: high-level systems and deployed containers/services
  • Module diagram: major frontend/backend modules and their dependencies
  • Class diagram: only key backend classes (5–15), not every class

---

Specification Document Template (write exactly this structure)

{{Project Name}} — Specification

Version: {{date}}
Repo: {{repo identifier if known}}
Primary stack: {{inferred stack}}

Assumptions & Open Questions

• Assumption: ...
• Open question: ...

1. Architecture and technology choices

1.1 Architecture overview

• System style (e.g., monolith, modular monolith, microservices)
• Key components and responsibilities
• Trust boundaries (auth, secrets, network zones) if applicable

1.2 Technology choices (with rationale)

Provide a table:

Area	Choice	Evidence	Why this choice	Alternatives considered

1.3 Non-functional requirements (NFRs)

• Performance, availability, security, observability, compliance, cost
• What the repo suggests (or what’s missing)

2. Data model

2.1 Conceptual model

• List core entities and what they represent
• Identify ownership and lifecycle boundaries

2.2 Logical model (tables/collections)

Provide a table:

Entity/Table	Primary key	Key fields	Relationships	Notes

2.3 Data integrity & constraints

• Uniqueness, foreign keys, soft delete, audit fields, tenancy strategy, etc.

3. Key processes

List 3–7 “key processes” (system behaviors) using this structure:

• Process name
  • Trigger:
  • Inputs:
  • Outputs:
  • Key steps:
  • Error cases:
  • Observability (logs/metrics/traces):

4. Pseudocode

For each key process, provide pseudocode:

• Use clear function signatures
• Include validation, error handling, retries/transactions where relevant

Example format:

function ProcessName(input):
  validate input
  begin transaction (if needed)
  ...
  return result