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:

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:

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