Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 14 additions & 31 deletions .agents/skills/docslime-adr/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ description: Creates and fills the next-numbered DocSlime Architecture Decision

# DocSlime ADR

Record a single architecture decision as an ADR — the context, the options, the choice, and
its consequences — so the reasoning lives in the repo alongside the code.
Record a single architecture decision as an ADR — the context, the options, the choice, and its consequences — so the reasoning lives in the repo alongside the code.

## When to Use

Expand All @@ -18,16 +17,13 @@ its consequences — so the reasoning lives in the repo alongside the code.

## Prerequisites

The `docs/` tree must exist (run **docslime-init** if not) and `docslime` must be installed (run
**docslime-install** if not). ADRs live in `docs/engineering/adrs/`. Older initialized trees
may still use `docs/3-ENGINEERING/ADRs/`; the CLI continues there rather than splitting the log.
The `docs/` tree must exist (run **docslime-init** if not) and `docslime` must be installed (run **docslime-install** if not). ADRs live in `docs/engineering/adrs/`. Older initialized trees may still use `docs/3-ENGINEERING/ADRs/`; the CLI continues there rather than splitting the log.

## Guardrails

- Record one decision per ADR. Do not use an ADR to relitigate the whole system.
- Keep accepted ADRs immutable; create a new superseding ADR for changed decisions.
- Tie context back to requirement IDs, domain boundaries, constraints, or forces when they
are known.
- Tie context back to requirement IDs, domain boundaries, constraints, or forces when they are known.
- Ask the user what options were actually considered; do not invent alternatives for polish.

## Steps
Expand All @@ -38,34 +34,25 @@ may still use `docs/3-ENGINEERING/ADRs/`; the CLI continues there rather than sp
docslime add adr <short-slug>
```

`<slug>` is a short kebab name for the decision, e.g. `use-postgres`. `docslime` writes
`docs/engineering/adrs/NNNN-<slug>.md`, where `NNNN` is the next number after the highest
existing record (`0001` if there are none). The slug is lower-cased and hyphenated
automatically, so `docslime add adr "Use Postgres"` produces `0002-use-postgres.md`.
`<slug>` is a short kebab name for the decision, e.g. `use-postgres`. `docslime` writes `docs/engineering/adrs/NNNN-<slug>.md`, where `NNNN` is the next number after the highest existing record (`0001` if there are none). The slug is lower-cased and hyphenated automatically, so `docslime add adr "Use Postgres"` produces `0002-use-postgres.md`.

If you don't know the slug yet, ask the user for a 2–4 word name for the decision first.

### 2 — Fill it in by interviewing about ONE decision

Open the new file and follow its inline `<!-- LLM: ... -->` guidance. Keep it focused — one
ADR, one decision. Work through the sections:
Open the new file and follow its inline `<!-- LLM: ... -->` guidance. Keep it focused — one ADR, one decision. Work through the sections:

- **Title & metadata** — set `ADR-NNNN: <Title>`, `Status: Proposed` (→ `Accepted` once
decided), today's `Date`, and the deciders.
- **Context** — the forces, constraints, and requirements that force a choice. Reference
requirement IDs from `../../REQUIREMENTS.md` where relevant. State facts, not the choice.
- **Options considered** — the realistic alternatives (including "do nothing"), each with
pros and cons. Ask the user what was actually on the table.
- **Title & metadata** — set `ADR-NNNN: <Title>`, `Status: Proposed` (→ `Accepted` once decided), today's `Date`, and the deciders.
- **Context** — the forces, constraints, and requirements that force a choice. Reference requirement IDs from `../../REQUIREMENTS.md` where relevant. State facts, not the choice.
- **Options considered** — the realistic alternatives (including "do nothing"), each with pros and cons. Ask the user what was actually on the table.
- **Decision** — the option chosen and the reasoning. Be definite.
- **Consequences** — positive, negative, and follow-up. Be honest about the trade-offs.

Ask one focused question at a time and reflect answers back. Remove each `<!-- LLM: ... -->`
comment and replace each `_italic prompt_` as you complete its section.
Ask one focused question at a time and reflect answers back. Remove each `<!-- LLM: ... -->` comment and replace each `_italic prompt_` as you complete its section.

### 3 — Update the decision log

Add a row for this ADR to the table in `docs/engineering/adrs/README.md` (or the legacy ADR
index when the CLI deliberately continued an older tree):
Add a row for this ADR to the table in `docs/engineering/adrs/README.md` (or the legacy ADR index when the CLI deliberately continued an older tree):

```
| 0002 | Use Postgres | Accepted | 2026-06-02 |
Expand All @@ -75,8 +62,7 @@ Keep the log in sync — one row per ADR file.

### 4 — Treat accepted ADRs as immutable

Once an ADR is `Accepted`, don't rewrite it. To change the decision, create a **new** ADR
that supersedes it, and set the old one's status to `Superseded by ADR-NNNN`.
Once an ADR is `Accepted`, don't rewrite it. To change the decision, create a **new** ADR that supersedes it, and set the old one's status to `Superseded by ADR-NNNN`.

### 5 — Verify and report

Expand All @@ -90,13 +76,10 @@ grep -rn "LLM:" docs/engineering/adrs/ docs/3-ENGINEERING/ADRs/ 2>/dev/null

When the new ADR and the log are clean, summarize the decision and the record's number.

Also confirm the ADR file exists at the expected `NNNN-<slug>.md` path and the ADR index has
one row for that file.
Also confirm the ADR file exists at the expected `NNNN-<slug>.md` path and the ADR index has one row for that file.

## Failure Handling

- If the docs tree or ADR directory is missing, run **docslime-init** or create the missing ADR
path through `docslime add adr <slug>`.
- If the docs tree or ADR directory is missing, run **docslime-init** or create the missing ADR path through `docslime add adr <slug>`.
- If the slug is unknown, ask for a 2-4 word decision name before creating the record.
- If the decision is not actually made, keep the ADR status `Proposed` and list the unresolved
question rather than forcing `Accepted`.
- If the decision is not actually made, keep the ADR status `Proposed` and list the unresolved question rather than forcing `Accepted`.
64 changes: 17 additions & 47 deletions .agents/skills/docslime-fill/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ description: Fills scaffolded DocSlime documents by interviewing the user and re

# DocSlime Fill

Fill in one of the scaffolded `docs/` documents by interviewing the user and following the
inline `<!-- LLM: ... -->` guidance baked into each template.
Fill in one of the scaffolded `docs/` documents by interviewing the user and following the inline `<!-- LLM: ... -->` guidance baked into each template.

## When to Use

Expand All @@ -18,15 +17,11 @@ inline `<!-- LLM: ... -->` guidance baked into each template.

## Prerequisites

The `docs/` tree must exist. If it doesn't, run the **docslime-init** skill first. If you only
need to add one missing document, create it with `docslime add <name>` (run `docslime list` to
see names).
The `docs/` tree must exist. If it doesn't, run the **docslime-init** skill first. If you only need to add one missing document, create it with `docslime add <name>` (run `docslime list` to see names).

## The document lifecycle

This is a menu and a common order, not a mandatory checklist. First identify which documents
belong in this repo, then fill durable context and follow relevant evidence through delivery
and production learning. Revisit earlier docs when observation changes what the team knows:
This is a menu and a common order, not a mandatory checklist. First identify which documents belong in this repo, then fill durable context and follow relevant evidence through delivery and production learning. Revisit earlier docs when observation changes what the team knows:

1. `PRODUCT.md` — project-level product context, when this repo owns it
2. `DESIGN.md` — reusable product or interface design rules, when applicable
Expand All @@ -41,59 +36,39 @@ and production learning. Revisit earlier docs when observation changes what the
## Guardrails

- Do not invent product facts, requirements, architecture, tests, decisions, users, or metrics.
- Do not fill or preserve a document merely because the template created it. Recommend
removing, merging, or replacing irrelevant docs with a link to the authoritative source.
- Treat developers, operators, integrators, and coding agents as real users when they consume
a service, library, SDK, CLI, or API; retain `experience/` when DX or agent experience matters.
- Do not fill or preserve a document merely because the template created it. Recommend removing, merging, or replacing irrelevant docs with a link to the authoritative source.
- Treat developers, operators, integrators, and coding agents as real users when they consume a service, library, SDK, CLI, or API; retain `experience/` when DX or agent experience matters.
- Ask one focused question at a time when facts are missing.
- Preserve existing user-written content unless it conflicts with a correction the user gives.
- Keep requirements testable and solution-neutral, architecture grounded in real domain
boundaries, and testing mapped to Given/When/Then behavior.
- Keep requirements testable and solution-neutral, architecture grounded in real domain boundaries, and testing mapped to Given/When/Then behavior.
- Keep publishing grounded in actual artifacts, gates, promotion, verification, and rollback.
- Present Semantic Versioning and Conventional Commits as optional publishing practices. Read
the existing workflow first; never impose enforcement, rewrite history, or change release
automation without explicit team agreement.
- Present Semantic Versioning and Conventional Commits as optional publishing practices. Read the existing workflow first; never impose enforcement, rewrite history, or change release automation without explicit team agreement.
- Keep observability tied to user outcomes as well as system health; never invent telemetry.

## Steps

### 1 — Read the document and its guidance

Open the target file (e.g. `docs/PRODUCT.md`) and confirm it serves this project's actual
consumers before filling it. A backend API in a large organization may reasonably omit local
product strategy and visual design docs while keeping experience artifacts for developer and
agent workflows. Each retained template carries two kinds of
authoring cues:
Open the target file (e.g. `docs/PRODUCT.md`) and confirm it serves this project's actual consumers before filling it. A backend API in a large organization may reasonably omit local product strategy and visual design docs while keeping experience artifacts for developer and agent workflows. Each retained template carries two kinds of authoring cues:

- A **file-level** `<!-- LLM: ... -->` comment at the top with overall instructions and
ordering for that document.
- A **section-level** `<!-- LLM: ... -->` comment under each heading listing the specific
questions to ask and how to write that section. Italic prompts like `_What problem are we
solving?_` are placeholders to replace with real prose.
- A **file-level** `<!-- LLM: ... -->` comment at the top with overall instructions and ordering for that document.
- A **section-level** `<!-- LLM: ... -->` comment under each heading listing the specific questions to ask and how to write that section. Italic prompts like `_What problem are we solving?_` are placeholders to replace with real prose.

Read all of them before asking anything, so you understand the whole document.

### 2 — Interview the user, one focused question at a time

Follow the guidance comments. Ask **one focused question at a time**, reflect the user's
answer back in your own words, and confirm before writing. Don't dump every question at
once and don't invent facts — if the user doesn't know something, note it and move on.
Follow the guidance comments. Ask **one focused question at a time**, reflect the user's answer back in your own words, and confirm before writing. Don't dump every question at once and don't invent facts — if the user doesn't know something, note it and move on.

Pull context from the applicable lifecycle: when filling `REQUIREMENTS.md`, ground it in the
retained local docs, experience evidence, and linked organization-level sources. When filling
observability, trace signals back to requirements and discovery hypotheses.
Pull context from the applicable lifecycle: when filling `REQUIREMENTS.md`, ground it in the retained local docs, experience evidence, and linked organization-level sources. When filling observability, trace signals back to requirements and discovery hypotheses.

### 3 — Write each section

Replace the italic prompt and write the real content per the section's guidance. Match the
intended altitude — `PRODUCT.md` stays tight (it's product context, not a spec);
`engineering/ARCHITECTURE.md` can go deeper.
Replace the italic prompt and write the real content per the section's guidance. Match the intended altitude — `PRODUCT.md` stays tight (it's product context, not a spec); `engineering/ARCHITECTURE.md` can go deeper.

### 4 — Remove the guidance comment

Once a section is written, **delete that section's `<!-- LLM: ... -->` comment**. When the
whole document is done, remove the file-level comment too. A finished doc has no `LLM:`
comments and no leftover italic prompts.
Once a section is written, **delete that section's `<!-- LLM: ... -->` comment**. When the whole document is done, remove the file-level comment too. A finished doc has no `LLM:` comments and no leftover italic prompts.

### 5 — Verify nothing is left

Expand All @@ -105,18 +80,13 @@ See the verification section below before reporting completion.
grep -rn "LLM:" docs/
```

Anything still listed is unfinished. When the target doc is clean, summarize what you wrote
and offer to move to the next document in the chain, record an architecture decision with
the **docslime-adr** skill, or run **docslime-kiss** once enough docs exist to tighten bloat and
generic AI prose.
Anything still listed is unfinished. When the target doc is clean, summarize what you wrote and offer to move to the next document in the chain, record an architecture decision with the **docslime-adr** skill, or run **docslime-kiss** once enough docs exist to tighten bloat and generic AI prose.

Also check for leftover italic placeholders in the target file and confirm any requirement
IDs, BDD scenarios, test references, or ADR links you added point to real docs or known gaps.
Also check for leftover italic placeholders in the target file and confirm any requirement IDs, BDD scenarios, test references, or ADR links you added point to real docs or known gaps.

## Failure Handling

- If `docs/` does not exist, run **docslime-init** first.
- If the target document is ambiguous, ask which file to fill.
- If the user does not know an answer, record a clear open question instead of guessing.
- If filling reveals a durable product or technical decision, offer **docslime-adr** rather
than burying the decision in prose.
- If filling reveals a durable product or technical decision, offer **docslime-adr** rather than burying the decision in prose.
Loading
Loading