Docs

Project memory system. Pick an action:

/docs sync
— Map codebase to references, update roadmap statuses
/docs research
— Discover and formalize what to build next into a roadmap doc
/docs work
— Execute a roadmap item, then update references

Match the first argument to the corresponding section below.

Core Model

```
docs/reference/
```
= what exists in the codebase. Sync writes here.
```
docs/roadmap/
```
= what should exist but doesn't yet. Research writes here. Organized by status.
```
docs/decisions/
```
= decision records. Any command can create these.
```
docs/logs/
```
= chronological work history. Work writes here.

Rule Levels

Required — Must be followed.
Recommended — Strong default guidance.

Global Rules (required)

Command contract — only
```
sync
```
,
```
research
```
,
```
work
```
.
Docs root + folder contract — this skill manages
```
docs/
```
with only these top-level folders:
- ```
docs/reference/
```
- ```
docs/roadmap/
```
- ```
docs/decisions/
```
- ```
docs/logs/
```
- Inside
```
docs/reference/
```
  , use:
  - features/
  - architecture/
  - conventions/
  - runbooks/
  - pitfalls/
- Inside
```
docs/roadmap/
```
  , use status folders:
  - proposed/
    — ideas formalized, not started
  - in-progress/
    — actively being worked on
  - completed/
    — fully shipped
  - archived/
    — superseded, rejected, or deprioritized

Naming + date rules

```
reference/*
```
→
```
kebab-case.md
```

roadmap/**

decisions/

→

YYYY-MM-DD-kebab-case.md

```
logs/
```
→
```
YYYY-MM.md
```
monthly logs
Dates must be zero-padded ISO 8601:
```
YYYY-MM-DD
```
.

Append-only history — for
```
logs/
```
and
```
decisions/
```
, add new files instead of rewriting history.
Roadmap status lifecycle — track status by moving docs between roadmap folders:
- ```
proposed/
```
  →
```
in-progress/
```
  →
```
completed/
```
- Items that won't be built go to
```
archived/
```
  with a note explaining why (superseded, rejected, deprioritized)
- Every roadmap doc must still have a
```
## Status
```
  line for quick context (e.g.,
```
Proposed
```
  ,
```
In Progress
```
  ,
```
Completed (YYYY-MM-DD)
```
  ,
```
Archived — superseded by [link]
```
  )
Policy files — if
```
AGENTS.md
```
and/or
```
CLAUDE.md
```
exist, keep their docs-memory guidance aligned.
Conflict behavior — if repository conventions conflict with these defaults, do not rewrite conventions silently. Report the mismatch and ask the user before changing direction.

Global Rules (recommended)

Prefer focused, single-purpose docs.
Prefer updating existing docs before creating new ones.
Keep docs concrete and scannable.
Treat code as ground truth; avoid full schema dumps in docs.

sync

Fully map the codebase into

docs/reference/

. Also update roadmap statuses for shipped work.

Completeness requirement: Sync must resolve ALL findings before completing. Do not defer undocumented systems, stale docs, or partial docs to "a future sync." Every implemented system must have a corresponding reference doc when sync finishes. If the scope is large, batch the work — but finish it in this run.

1. Ensure structure

Runs every sync to keep the folder structure intact. Idempotent — creates what's missing, leaves everything else alone. Never overwrites or removes existing files or folders.

Ensure all folders exist (create any that are missing):

docs/
├── README.md
├── reference/
│   ├── features/
│   ├── architecture/
│   ├── conventions/
│   ├── runbooks/
│   └── pitfalls/
├── roadmap/
│   ├── proposed/
│   ├── in-progress/
│   ├── completed/
│   └── archived/
├── decisions/
└── logs/

If
```
docs/README.md
```
is missing, create it with:
- A short purpose line for
```
docs/
```
- Folder purposes and structure description
- Naming/date/append-only conventions from Global Rules
If
```
AGENTS.md
```
and/or
```
CLAUDE.md
```
exist but lack docs guidance, add a short section:
- ```
docs/
```
  is the project memory system. See
```
docs/README.md
```
  for structure and conventions.
- Update relevant docs when behavior, architecture, or workflows change.

2. Audit docs vs code

Read

docs/README.md

, then review all files under

docs/reference/

docs/roadmap/

docs/decisions/

, and

docs/logs/

Use repository search to check what exists in code (schema, services, routes, UI, jobs, APIs).
Compare every reference doc against current code for accuracy.
Identify implemented systems that have no reference doc.
Check roadmap items — have any been shipped? Should any move between status folders?

3. Classify findings

Use this taxonomy:

Stale — reference doc is materially incorrect vs current code
Partial — reference doc exists but is missing significant implemented behavior
Undocumented — important implemented system has no reference doc
Roadmap shipped — roadmap item has been implemented and should move to
```
completed/
```

4. Sync (required — must resolve ALL findings, no deferral)

Resolve every finding discovered in steps 2-3. Do not skip, defer, or deprioritize any item:

Stale docs — update to match current code.
Partial docs — fill in the missing sections from code evidence.
Undocumented systems — create new reference docs (
```
features/
```
,
```
architecture/
```
,
```
conventions/
```
,
```
runbooks/
```
, or
```
pitfalls/
```
as appropriate).
Shipped roadmap items — move the roadmap doc to
```
completed/
```
and update its
```
## Status
```
line.
Add or update
```
conventions/
```
,
```
runbooks/
```
, and
```
pitfalls/
```
entries when repository evidence exists.

If a change would alter repository conventions or policy direction, report the mismatch and ask before making that change.

Output Contract (required)

When

/docs sync

completes, return all of:

Bootstrap status —
```
created
```
or
```
already present
```
Coverage table with this exact header:

| System | Doc | Status | Action taken |
|--------|-----|--------|--------------|

Summary — counts by status (stale fixed, partial filled, undocumented created, roadmap updated)
Docs changes made — list updated/created/moved paths, or
```
none
```

research

Discover what to build next and formalize it into a roadmap doc.

1. Scan for candidates

Work through these lenses. Not all will apply to every product — use what's relevant:

Usage and behavior — What are users actually doing?

If analytics tools are available, check usage patterns, funnels, retention, and drop-off points
Identify features that are heavily used (double down) vs unused (cut or rethink)

Demand — What are users asking for?

Check issue trackers, feature request backlogs, and support channels for patterns
Look for frequently requested capabilities or common complaints

Pain — What's broken or frustrating?

Check

docs/reference/pitfalls/

and

docs/reference/runbooks/

for recurring operational pain

Look at bug reports, incident history, and support escalations

Strategy — What's the current direction?

Read
```
docs/roadmap/
```
for existing plans and their statuses
Read
```
docs/reference/features/
```
for gaps, limitations, and natural next steps
Consider business goals and priorities the user has communicated

Landscape — What's happening externally?

Research competitors, adjacent tools, and market shifts if relevant
Identify opportunities others are capitalizing on

Technical opportunity — What does the codebase reveal?

Scan code for
```
TODO
```
,
```
FIXME
```
,
```
HACK
```
, stubs, and dead paths
Identify tech debt that's actively slowing down development

Vision — What's possible that doesn't exist yet?

What adjacent problems could we solve with what we've already built?
What emerging capabilities or trends could we leverage?
What would the product look like if we removed current constraints?
What would make users say "I didn't know I needed this"?

Narrow to user-specified domain if provided.

2. Rank candidates

Rank by:

impact (user value, pain reduction)
readiness (how much groundwork already exists)
size (
```
small
```
,
```
medium
```
,
```
large
```
)

3. Propose shortlist

Use this exact header:

| # | What | Why now | Size | Readiness | Exists | Missing |
|---|------|---------|------|-----------|--------|---------|

4. Formalize the chosen item

Once the user picks an item (or accepts the recommendation):

Create a roadmap doc at

docs/roadmap/proposed/YYYY-MM-DD-slug.md

Required sections:
- Opening line (plain-language summary of the problem)
- Status (
```
Proposed
```
  )
- Why (problem statement, evidence, user impact)
- What (concrete scope, deliverables)
- How It Fits In (relation to existing systems, dependencies)
- Non-Goals (explicit scope boundaries)
- Open Questions (unresolved decisions)
Add cross-links from related reference docs if useful

Output Contract (required)

When

/docs research

completes, return all of:

Shortlist table (3-5 rows)
Recommended item (
```
#<n>
```
+ one-sentence reason)
If formalized: roadmap doc path, open questions
Next command suggestion (
```
/docs work <path>
```
or another
```
/docs research
```
for a different domain)

work

Execute a roadmap item. Build it, then close the loop in docs.

1. Understand task

If user gives a roadmap doc path, read it first
If user gives a description, find the related roadmap doc in
```
docs/roadmap/
```
If no roadmap doc exists, ask: should we create one first (
```
/docs research
```
) or proceed directly?
If ambiguous, clarify scope briefly
Move the roadmap doc to
```
in-progress/
```
if it's still in
```
proposed/
```

2. Gather implementation context

Read the roadmap doc and any related reference docs
Inspect existing code patterns in touched areas
Check project rules and conventions

3. Build

Plan first if scope is large (using your environment's planning workflow)
Implement the change
Run verification commands

4. Close the loop

After implementation is complete:

Update reference docs — create or update
```
docs/reference/
```
docs to reflect the new code (features, architecture, conventions, runbooks, pitfalls as appropriate)

Update roadmap doc — move to

completed/

and update

## Status

Completed (YYYY-MM-DD)

, or move to

completed/

with

Partially Completed (YYYY-MM-DD)

and notes on what remains

Log entry — append a summary to
```
docs/logs/YYYY-MM.md
```

Output Contract (required)

When

/docs work

completes, return all of:

Scope delivered
Code files changed
Verification — commands + pass/fail
Docs updated — list reference/roadmap/log paths, or
```
none
```
Follow-ups — remaining work or
```
none
```

docs

NPX Install

Tags

SKILL.md Content

Docs

Core Model

Rule Levels

Global Rules (required)

Global Rules (recommended)

sync

1. Ensure structure

2. Audit docs vs code

3. Classify findings

4. Sync (required — must resolve ALL findings, no deferral)

Output Contract (required)

research

1. Scan for candidates

2. Rank candidates

3. Propose shortlist

4. Formalize the chosen item

Output Contract (required)

work

1. Understand task

2. Gather implementation context

3. Build

4. Close the loop

Output Contract (required)