Create a thorough documentation of the current system. This is the shared
foundation that all other spec skills build on.
The system description lives in specs/system/ and captures what the system
is and does right now — not what it should become.
Steps
-
Check for existing documentation
Check if specs/system/ already exists. If it does, read all files in it to
understand what's already documented.
- If documentation exists: review it against the current codebase, update
what's outdated, and fill gaps.
- If no documentation exists: create it from scratch by exploring the
codebase.
-
Explore the codebase
Thoroughly investigate the project to understand:
- What the system does (its purpose, who it serves)
- How it's built (technologies, frameworks, patterns)
- What domain it models (entities, processes, rules)
- What it interacts with (external systems, APIs, services)
Read configuration files, entry points, key modules, data models, and any
existing documentation (README, comments, etc.).
-
Create or update specs/system/domain.md
Document the domain the system models:
- Purpose — What problem does this system solve? Who uses it?
- Vocabulary — Domain-specific terms with clear definitions. These are
the words the team uses when talking about the system.
- Concepts and entities — The core things the system models and their
relationships. Use Mermaid diagrams to visualize.
- Actors — People, roles, and external systems that interact with the
system. What can each actor do?
- Processes — Key workflows and business processes. What triggers them?
What are the steps? What are the outcomes?
- Rules and constraints — Business rules, invariants, validation rules
that the domain enforces.
-
Create or update specs/system/architecture.md
Document how the system is built:
- Overview — High-level architecture style (monolith, microservices,
serverless, etc.). Use a Mermaid diagram to show the big picture.
- Technology stack — Languages, frameworks, libraries, databases, and
their roles.
- Components — Major modules, services, or packages and what each is
responsible for. How they communicate.
- Data — How data is stored, what databases or stores are used, key data
models and their relationships.
- System boundaries — Where this system ends and others begin. APIs
exposed, APIs consumed.
- External systems — Third-party services, integrations, dependencies
on other internal systems.
- Infrastructure — How the system is deployed, hosted, and operated
(if discoverable from the codebase).
-
Create or update specs/system/functional.md
Document what the system does from a user's perspective — the capabilities
it provides, independent of how they're implemented:
- Features — The concrete things users can do. Group by area or module.
For each feature: what it does, who uses it, and any notable behaviors.
- User journeys — Key end-to-end flows that span multiple features.
Use Mermaid sequence or flowchart diagrams to illustrate the most
important ones.
- Inputs and outputs — What data goes in, what comes out. Forms,
uploads, reports, notifications, exports — document what the system
accepts and produces.
- States and transitions — Key entities that have lifecycle states
(e.g., draft → published → archived). Use Mermaid state diagrams.
- Permissions and visibility — What different user roles can see and
do. Which features are gated behind roles, subscriptions, or flags.
- Edge cases and known limitations — Documented or discovered limits,
quotas, unsupported scenarios, and intentional omissions.
-
Identify additional perspectives
If the codebase reveals other important aspects not covered by domain,
architecture, and functional, create additional files in specs/system/.
For example:
security.md — Authentication, authorization, data protection patterns
api.md — Public API surface, versioning, conventions
data-model.md — Detailed entity-relationship documentation
Only create these if the codebase warrants it — don't force perspectives
that aren't meaningful for this system.
-
Present for review
Show the user a summary of what was documented:
- Files created or updated
- Key findings about the system
- Any areas where information was unclear or assumptions were made
Output
## System Documentation Complete
**Location:** specs/system/
### Files
- domain.md — <brief summary>
- architecture.md — <brief summary>
- functional.md — <brief summary>
### Key Findings
- <notable discovery about the system>
- <notable discovery about the system>
### Assumptions / Gaps
- <anything unclear that the user should verify>
Guardrails
- Document what is, not what should be — this is a snapshot of the current
system
- Ground everything in the actual codebase — don't speculate about things you
can't find evidence for
- Use Mermaid diagrams wherever they help clarify structure or flow
- Flag assumptions clearly — if you're unsure about something, say so
- Keep vocabulary definitions precise — these terms become the shared language
for all spec artifacts
- Don't duplicate what's already in a README — reference it instead
- When updating existing documentation, preserve information that's still
accurate and note what changed