Documentation Lifecycle

DocSlime is not just a folder generator. It encodes a full product-and-engineering loop:
learn from users, write a testable contract, shape the domain, prove behavior, ship verified
artifacts, and feed production evidence back into discovery.

The CLI scaffolds the tree. Agent skills do the judgment-heavy work. Your job is to keep the
trace honest: every important behavior should be followable from evidence to proof.

The closed loop

strategy -> product/design -> discovery -> requirements -> architecture -> testing
    ^                                                                          |
    +---- observation <- publishing <- verified build <------------------------+

How to use DocSlime day to day

1. Scaffold the tree

brew install DecisionNerd/tap/docslime   # once per machine
docslime init                            # once per repo
npx skills add DecisionNerd/DocSlime     # once per agent environment

docslime init creates the lifecycle-oriented docs/ tree and skips anything you already
wrote. Use docslime list to see what exists and docslime add <name> to add one missing
document.

2. Fill durable context first

Use docslime-fill (or /docslime-fill in a skill-aware agent) in this order:

1. PRODUCT.md — problem, vision, stakeholders, success measures
2. DESIGN.md — principles, voice, interaction rules for CLI/docs/site/skills
3. strategy/ — only when positioning or roadmap needs more room than PRODUCT.md
4. experience/ — evidence, journeys, opportunities, and behavior hypotheses

Each template carries <!-- LLM: ... --> guidance. The skill interviews you, replaces
prompts with real facts, and removes scaffolding comments when a section is done.

3. Translate evidence into a build contract

Fill REQUIREMENTS.md after product, design, and discovery context exist. Requirements must
be:

• Solution-neutral — say what must be true, not how to implement it
• Testable — each FR/NFR should be provable
• Traceable — link back to journeys or evidence in experience/

When a finding in experience/ identifies observable behavior the product must provide, it
becomes a requirement. Implementation choices belong in architecture or an ADR.

4. Shape the domain and record decisions (DDD)

Fill engineering/ARCHITECTURE.md to name the components, data, and boundaries that satisfy
the requirements. DocSlime uses Domain Driven Design lightly:

• Name the domain concepts that affect behavior (not abstract “document management”)
• Draw boundaries between CLI scaffold, agent skills, publishing, and observation
• Keep ubiquitous language consistent across requirements, architecture, and ADRs
• Stay light on small projects — say when a bounded context is not worth formalizing

When a choice is hard to reverse, record it:

docslime add adr choose-storage-boundary

Then use docslime-adr to write the decision in project vocabulary with context,
consequences, and links to requirements.

5. Prove behavior (TDD+BDD)

Fill engineering/TESTING.md to define how the contract is verified:

The traceability bar: every important FR should map to at least one scenario and one test (or
an explicit reason why automation is not appropriate).

6. Ship and verify

Fill engineering/PUBLISHING.md with the real promotion path: artifacts, versioning, CI
gates, deployment verification, and rollback. DocSlime itself promotes staging → main
for the site and uses tag-driven releases for the CLI.

7. Learn from production

Fill engineering/OBSERVABILITY.md to connect system health and user-outcome signals back to
requirements and discovery hypotheses. When production contradicts an assumption, update
experience/ or REQUIREMENTS.md — do not let stale docs pretend the old world is still true.

8. Keep it lean

Run docslime-kiss before merging documentation-heavy changes. It looks for:

• Contradictions between product, requirements, and architecture
• Generic AI prose with no testable claim
• Weak traceability (requirements with no tests, ADRs with no requirement link)
• Leftover <!-- LLM: --> guidance or _italic prompts_

UX: continuous discovery in practice

The experience/ folder is DocSlime’s UX and product-discovery workspace. It is not a
feature backlog dump.

What belongs here:

• Observed needs with evidence (support tickets, interviews, usage, maintainer feedback)
• User journeys and desired outcomes
• Opportunities and hypotheses (“we believe X will improve Y because Z”)
• Given/When/Then scenarios that should become requirements
• Success signals you can observe after release

What does not belong here:

• Implementation plans (those live in architecture or ADRs)
• Committed behavior (that lives in REQUIREMENTS.md)
• Unvalidated assumptions written as facts

When evidence earns its own file, create a focused lowercase-kebab-case markdown file under
experience/ using the artifact shape documented on the Experience page.

DDD: domain language without ceremony

DocSlime does not force heavyweight Domain Driven Design. It asks architecture docs to make
the system’s nouns and boundaries explicit enough that the next human or agent can reason
about change.

Minimum useful DDD evidence:

If a project has no meaningful domain split, say so in architecture instead of inventing
bounded contexts.

TDD+BDD: from intent to proof

DocSlime’s development method treats docs and tests as one trace:

evidence -> requirement (FR-12) -> BDD scenario -> automated test -> CI gate -> release

Requirements (REQUIREMENTS.md) hold stable IDs and observable statements.

BDD scenarios live in engineering/TESTING.md (and optionally in experience/ while
still hypothesis-level) as Given/When/Then prose.

TDD tests are the automated proof — in DocSlime’s own repo, Rust integration tests run the
compiled docslime binary against throwaway directories and assert on files and exit codes.

CI is the promotion gate — if tests fail, the behavior contract is not met.

Dogfooding example: DocSlime’s engineering/TESTING.md maps every FR
to a tests/cli.rs case. The site build and agent-skill validation run in CI alongside the
CLI suite.

Command and skill reference

When to update what

Read next

• Experience — continuous discovery practice and artifact shape
• Requirements — the behavior contract
• Architecture — system shape and domain boundaries
• Testing — BDD scenarios and test mapping
• Agent Skills — skill invocation and quality bar