From 2b389a311e0706f1906f5d582d0476c77c18aea7 Mon Sep 17 00:00:00 2001 From: David Spencer <1526975+DecisionNerd@users.noreply.github.com> Date: Tue, 14 Jul 2026 12:44:46 -0600 Subject: [PATCH] docs: remove line-length wrapping from markdown --- .agents/skills/docslime-adr/SKILL.md | 45 ++++-------- .agents/skills/docslime-fill/SKILL.md | 64 +++++----------- .agents/skills/docslime-init/SKILL.md | 59 ++++----------- .agents/skills/docslime-install/SKILL.md | 19 ++--- .agents/skills/docslime-kiss/SKILL.md | 41 +++-------- .../2026-07-09T20-59-43Z__docs-index-md.md | 5 +- .../2026-07-09T21-58-35Z__docs-index-md.md | 31 +++----- .prettierignore | 2 + .prettierrc.json | 3 + README.md | 60 ++++----------- assets/adr.md | 23 ++---- docs/experience/README.md | 10 +++ package-lock.json | 19 +++++ package.json | 7 +- scripts/format-markdown-comments.mjs | 73 +++++++++++++++++++ templates/DESIGN.md | 46 ++++-------- templates/PRODUCT.md | 28 ++----- templates/README.md | 38 +++------- templates/REQUIREMENTS.md | 40 +++------- templates/engineering/ARCHITECTURE.md | 51 ++++--------- templates/engineering/OBSERVABILITY.md | 40 ++++------ templates/engineering/PUBLISHING.md | 44 +++-------- templates/engineering/README.md | 21 ++---- templates/engineering/TESTING.md | 47 ++++-------- templates/engineering/adrs/README.md | 15 ++-- templates/experience/README.md | 42 +++++------ templates/strategy/README.md | 19 ++--- 27 files changed, 344 insertions(+), 548 deletions(-) create mode 100644 .prettierignore create mode 100644 .prettierrc.json create mode 100644 scripts/format-markdown-comments.mjs diff --git a/.agents/skills/docslime-adr/SKILL.md b/.agents/skills/docslime-adr/SKILL.md index de57d9b..6568bc2 100644 --- a/.agents/skills/docslime-adr/SKILL.md +++ b/.agents/skills/docslime-adr/SKILL.md @@ -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 @@ -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 @@ -38,34 +34,25 @@ may still use `docs/3-ENGINEERING/ADRs/`; the CLI continues there rather than sp docslime add adr ``` -`` is a short kebab name for the decision, e.g. `use-postgres`. `docslime` writes -`docs/engineering/adrs/NNNN-.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`. +`` is a short kebab name for the decision, e.g. `use-postgres`. `docslime` writes `docs/engineering/adrs/NNNN-.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 `` guidance. Keep it focused — one -ADR, one decision. Work through the sections: +Open the new file and follow its inline `` guidance. Keep it focused — one ADR, one decision. Work through the sections: -- **Title & metadata** — set `ADR-NNNN: `, `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 | @@ -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 @@ -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`. diff --git a/.agents/skills/docslime-fill/SKILL.md b/.agents/skills/docslime-fill/SKILL.md index 80ec81d..1f6f04a 100644 --- a/.agents/skills/docslime-fill/SKILL.md +++ b/.agents/skills/docslime-fill/SKILL.md @@ -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 @@ -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 @@ -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 @@ -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. diff --git a/.agents/skills/docslime-init/SKILL.md b/.agents/skills/docslime-init/SKILL.md index e622f9e..3515bb1 100644 --- a/.agents/skills/docslime-init/SKILL.md +++ b/.agents/skills/docslime-init/SKILL.md @@ -5,10 +5,7 @@ description: Scaffolds and tailors the DocSlime docs starting template with docs # DocSlime Init -Scaffold a broad `docs/` starting tree into the current git repo so product context, continuous -discovery, requirements, design guidance, architecture, testing, delivery, observability, -and decisions can live alongside the code. Tailor the result to the project instead of -treating every generated file as mandatory. +Scaffold a broad `docs/` starting tree into the current git repo so product context, continuous discovery, requirements, design guidance, architecture, testing, delivery, observability, and decisions can live alongside the code. Tailor the result to the project instead of treating every generated file as mandatory. ## When to Use @@ -19,27 +16,21 @@ treating every generated file as mandatory. ## Prerequisites -The `docslime` binary must be installed. If `docslime --version` fails, run the -**docslime-install** skill first. +The `docslime` binary must be installed. If `docslime --version` fails, run the **docslime-install** skill first. ## Guardrails - Confirm you are at the target git repo root before writing files. -- `docslime init` is non-destructive by default; do not use `--force` unless the user asks to - overwrite existing scaffold files. -- Treat the scaffold as a template, not a compliance checklist. Recommend irrelevant files - for removal or consolidation and get confirmation before deleting them. -- When `docs/PRODUCT.md` and `docs/DESIGN.md` are useful, keep them in `docs/`; do not create - duplicate root bridge files for tools such as `impeccable`. -- Remember the CLI surface is `init`, `add`, and `list`. KISS review belongs to the - **docslime-kiss** skill. +- `docslime init` is non-destructive by default; do not use `--force` unless the user asks to overwrite existing scaffold files. +- Treat the scaffold as a template, not a compliance checklist. Recommend irrelevant files for removal or consolidation and get confirmation before deleting them. +- When `docs/PRODUCT.md` and `docs/DESIGN.md` are useful, keep them in `docs/`; do not create duplicate root bridge files for tools such as `impeccable`. +- Remember the CLI surface is `init`, `add`, and `list`. KISS review belongs to the **docslime-kiss** skill. ## Steps ### 1 — Confirm the working directory -Make sure you're at the root of the target git repo. The tree is created relative to the -current directory. +Make sure you're at the root of the target git repo. The tree is created relative to the current directory. ```bash pwd && ls @@ -70,24 +61,15 @@ docs/ └── adrs/ # Architecture Decision Records ``` -Existing files are **never overwritten**. `init` also recognizes the old numbered paths and -treats them as legacy matches rather than creating duplicate renamed docs. To intentionally -write the new template path, re-run with `docslime init --force`; this still does not remove -the legacy file. +Existing files are **never overwritten**. `init` also recognizes the old numbered paths and treats them as legacy matches rather than creating duplicate renamed docs. To intentionally write the new template path, re-run with `docslime init --force`; this still does not remove the legacy file. ### 3 — Tailor the template -Identify the project type and the people or agents who consume it, then keep only documents -that reduce ambiguity for those users. Link to an authoritative organization-level source -instead of duplicating it locally. +Identify the project type and the people or agents who consume it, then keep only documents that reduce ambiguity for those users. Link to an authoritative organization-level source instead of duplicating it locally. -For example, a backend API service in a large organization may not need local product -strategy or visual design docs when those concerns are owned elsewhere. It may still keep -`experience/` for developer experience, operator and integration journeys, and agent -experience when coding agents or other automated consumers use the API. +For example, a backend API service in a large organization may not need local product strategy or visual design docs when those concerns are owned elsewhere. It may still keep `experience/` for developer experience, operator and integration journeys, and agent experience when coding agents or other automated consumers use the API. -When removing or merging template files, update `docs/README.md` and affected links so the -remaining tree is intentional and navigable. Preserve real evidence and accepted decisions. +When removing or merging template files, update `docs/README.md` and affected links so the remaining tree is intentional and navigable. Preserve real evidence and accepted decisions. ### 4 — See what's there @@ -99,14 +81,9 @@ docslime list ### 5 — Orient and hand off -The docs form a lifecycle: strategy -> product/design -> discovery -> requirements -> -architecture -> testing -> publishing -> observability -> discovery. Each template contains -inline `<!-- LLM: ... -->` guidance for interviewing the user and filling the sections. +The docs form a lifecycle: strategy -> product/design -> discovery -> requirements -> architecture -> testing -> publishing -> observability -> discovery. Each template contains inline `<!-- LLM: ... -->` guidance for interviewing the user and filling the sections. -Tell the user the tailored tree is ready, and offer to start filling the first applicable -document with the **docslime-fill** skill. Begin with `docs/PRODUCT.md` only when project-level -product context belongs in this repo; otherwise start with the most relevant experience, -requirements, or architecture document. +Tell the user the tailored tree is ready, and offer to start filling the first applicable document with the **docslime-fill** skill. Begin with `docs/PRODUCT.md` only when project-level product context belongs in this repo; otherwise start with the most relevant experience, requirements, or architecture document. ## Verification @@ -115,14 +92,10 @@ docslime list test -f docs/PRODUCT.md && test -f docs/DESIGN.md ``` -Confirm created/skipped/legacy output is clear and that the retained tree matches the -project's real consumers. Missing template files are acceptable when their omission is -intentional and `docs/README.md` reflects the final shape. +Confirm created/skipped/legacy output is clear and that the retained tree matches the project's real consumers. Missing template files are acceptable when their omission is intentional and `docs/README.md` reflects the final shape. ## Failure Handling - If `docslime` is missing, stop and run **docslime-install** first. -- If the current directory is not a git repo or appears to be the wrong repo, ask before - scaffolding. -- If files already exist, report that `init` skipped them; do not overwrite unless the user - explicitly approves `docslime init --force`. +- If the current directory is not a git repo or appears to be the wrong repo, ask before scaffolding. +- If files already exist, report that `init` skipped them; do not overwrite unless the user explicitly approves `docslime init --force`. diff --git a/.agents/skills/docslime-install/SKILL.md b/.agents/skills/docslime-install/SKILL.md index 9f26038..224d2ba 100644 --- a/.agents/skills/docslime-install/SKILL.md +++ b/.agents/skills/docslime-install/SKILL.md @@ -17,16 +17,13 @@ Verify the `docslime` binary is available, and install it if it isn't. ## Prerequisites -- Run from the target repo when possible so the follow-up recommendation can inspect whether - `docs/` already exists. -- Prefer Homebrew on macOS/Linux when available; use the install script or source install as - fallbacks. +- Run from the target repo when possible so the follow-up recommendation can inspect whether `docs/` already exists. +- Prefer Homebrew on macOS/Linux when available; use the install script or source install as fallbacks. ## Guardrails - Install the `docslime` binary; do not describe `docslime-kiss` as a CLI command. -- Do not run `docslime init` from this skill unless the user explicitly asks for setup beyond - installation. Offer **docslime-init** as the next step instead. +- Do not run `docslime init` from this skill unless the user explicitly asks for setup beyond installation. Offer **docslime-init** as the next step instead. - If Homebrew reports a tap or trust issue, diagnose that path before switching installers. ## Steps @@ -77,13 +74,9 @@ You should see the version plus the `init`, `add`, and `list` subcommands. ## Failure Handling - If `docslime` is still missing, report the attempted install path and the exact failure. -- If Homebrew is present but the tap cannot be read, ask the user before changing taps or - trust settings. -- If no installer can run in the current environment, leave the repo untouched and give the - user the shortest manual install command that applies. +- If Homebrew is present but the tap cannot be read, ask the user before changing taps or trust settings. +- If no installer can run in the current environment, leave the repo untouched and give the user the shortest manual install command that applies. ### 4 — Report and offer next steps -Tell the user DocSlime is ready. If the current repo has no `docs/` tree yet, offer to run -the **docslime-init** skill to scaffold it; otherwise offer **docslime-fill** to start filling -documents in. +Tell the user DocSlime is ready. If the current repo has no `docs/` tree yet, offer to run the **docslime-init** skill to scaffold it; otherwise offer **docslime-fill** to start filling documents in. diff --git a/.agents/skills/docslime-kiss/SKILL.md b/.agents/skills/docslime-kiss/SKILL.md index 9460a4a..fa2c735 100644 --- a/.agents/skills/docslime-kiss/SKILL.md +++ b/.agents/skills/docslime-kiss/SKILL.md @@ -5,10 +5,7 @@ description: Reviews a DocSlime docs tree for KISS violations, bloat, generic AI # DocSlime KISS -Audit a DocSlime documentation tree for whether it is useful, lean, truthful, and traceable. -Use this when the user asks whether docs, requirements, architecture, design guidance, ADRs, -or testing docs are bloated, generic, "AI slop", overcomplicated, or not conforming to best -practice. +Audit a DocSlime documentation tree for whether it is useful, lean, truthful, and traceable. Use this when the user asks whether docs, requirements, architecture, design guidance, ADRs, or testing docs are bloated, generic, "AI slop", overcomplicated, or not conforming to best practice. ## When to Use @@ -41,17 +38,13 @@ Answer with evidence from the files, not vibes. - Prefer deleting filler over rewriting it into prettier filler. - Distinguish current behavior from target architecture or future ideas. - Do not invent missing strategy, requirements, domain boundaries, tests, or ADRs. -- Do not penalize a project for intentionally removing irrelevant template files. Judge - whether the retained tree serves its actual users, including developers and agents. -- Do not rewrite accepted ADRs except for path/index maintenance; create a superseding ADR - when a decision changes. +- Do not penalize a project for intentionally removing irrelevant template files. Judge whether the retained tree serves its actual users, including developers and agents. +- Do not rewrite accepted ADRs except for path/index maintenance; create a superseding ADR when a decision changes. ## Workflow -1. Read `docs/README.md` and inventory the retained docs before judging; do not assume every - default template should exist. -2. Identify the project type and its human and agent consumers, then check the applicable - trace across experience, requirements, architecture, testing, publishing, and observation. +1. Read `docs/README.md` and inventory the retained docs before judging; do not assume every default template should exist. +2. Identify the project type and its human and agent consumers, then check the applicable trace across experience, requirements, architecture, testing, publishing, and observation. 3. Identify bloat and slop with concrete file/line references. 4. Recommend the smallest change that makes the docs honest and useful. 5. If the user asked for edits, patch the docs directly and preserve real decisions. @@ -61,12 +54,9 @@ Answer with evidence from the files, not vibes. Good DocSlime docs are: - **Specific:** describe this project, not a generic software product. -- **Fit for purpose:** retain only docs that help this project's humans or agents make better - decisions; omissions are explicit and authoritative external context is linked. +- **Fit for purpose:** retain only docs that help this project's humans or agents make better decisions; omissions are explicit and authoritative external context is linked. - **Short enough to maintain:** no filler sections kept only because the template had them. -- **Traceable:** requirements serve evidence; architecture serves requirements; tests prove - behavior; publishing delivers verified artifacts; observability feeds production evidence - back into discovery. +- **Traceable:** requirements serve evidence; architecture serves requirements; tests prove behavior; publishing delivers verified artifacts; observability feeds production evidence back into discovery. - **Checkable:** requirements and testing claims can be verified. - **Current-state honest:** distinguish implemented behavior from target architecture or future ideas. - **Decision-light:** major durable choices live in ADRs; ordinary implementation detail does not. @@ -76,8 +66,7 @@ Good DocSlime docs are: Flag content when it has one or more of these smells: -- Generic praise words without concrete behavior: robust, scalable, seamless, intuitive, - comprehensive, user-friendly, cutting-edge. +- Generic praise words without concrete behavior: robust, scalable, seamless, intuitive, comprehensive, user-friendly, cutting-edge. - Repeated ideas copied across docs without adding new information. - Requirements that cannot be tested or that restate implementation details. - Architecture that describes a desired future as if it already exists. @@ -85,8 +74,7 @@ Flag content when it has one or more of these smells: - Design guidance that names vibes but gives no usable rules. - Testing docs that list commands but do not map back to behavior. - Publishing docs that conflate built, deployed, and verified state or omit rollback. -- Observability docs that list generic logs and metrics without user outcomes, ownership, or - a discovery feedback path. +- Observability docs that list generic logs and metrics without user outcomes, ownership, or a discovery feedback path. - Leftover `LLM:` comments, italic placeholders, or obviously templated prose. - Product, strategy, or design docs kept solely because the scaffold created them. - ADRs that relitigate the whole system instead of one decision. @@ -121,15 +109,10 @@ Then report: grep -rn "LLM:" docs/ ``` -For review-only runs, verify the report cites concrete files and names the smallest useful -cleanup. For edit runs, re-run the relevant search/checks and confirm the changed docs still -trace product/design -> discovery -> requirements -> architecture/testing -> publishing -> -observability -> discovery, with ADRs for durable choices. +For review-only runs, verify the report cites concrete files and names the smallest useful cleanup. For edit runs, re-run the relevant search/checks and confirm the changed docs still trace product/design -> discovery -> requirements -> architecture/testing -> publishing -> observability -> discovery, with ADRs for durable choices. ## Failure Handling - If `docs/` is missing, say DocSlime is not initialized and offer **docslime-init**. -- If docs are too incomplete to judge, report the missing inputs and suggest **docslime-fill** - for the next document in the chain. -- If evidence conflicts across docs, quote the conflicting file locations and ask the user - which source is current before rewriting facts. +- If docs are too incomplete to judge, report the missing inputs and suggest **docslime-fill** for the next document in the chain. +- If evidence conflicts across docs, quote the conflicting file locations and ask the user which source is current before rewriting facts. diff --git a/.impeccable/critique/2026-07-09T20-59-43Z__docs-index-md.md b/.impeccable/critique/2026-07-09T20-59-43Z__docs-index-md.md index b6929d9..6173b72 100644 --- a/.impeccable/critique/2026-07-09T20-59-43Z__docs-index-md.md +++ b/.impeccable/critique/2026-07-09T20-59-43Z__docs-index-md.md @@ -6,12 +6,13 @@ p1_count: 2 timestamp: 2026-07-09T20-59-43Z slug: docs-index-md --- + Method: dual-agent (A: 019f48a8-cfba-77c2-9f76-630962df1a34 · B: 019f48a8-f6e0-7a10-9c31-fd531f345f45) ## Design Health Score | # | Heuristic | Score | Key Issue | -|---|-----------|-------|-----------| +| --- | --- | --- | --- | | 1 | Visibility of System Status | 3 | Navigation, active page, search, theme, and copy controls exist; the homepage lacks a clear start-here state. | | 2 | Match System / Real World | 3 | Developer terms are accurate, but the opening phrase stays abstract before showing what happens to a repo. | | 3 | User Control and Freedom | 3 | Native docmd nav/search/theme affordances are strong; the homepage does not yet offer intent-based paths. | @@ -22,7 +23,7 @@ Method: dual-agent (A: 019f48a8-cfba-77c2-9f76-630962df1a34 · B: 019f48a8-f6e0- | 8 | Aesthetic and Minimalist Design | 1 | It is clean, but too default and quiet for a brand homepage. | | 9 | Error Recovery | 1 | No troubleshooting, version check, or recovery path for install/setup failure. | | 10 | Help and Documentation | 4 | The page is readable, searchable documentation with useful downstream links. | -| **Total** | | **25/40** | **Acceptable: strong docs shell, weak first impression.** | +| **Total** | | **25/40** | **Acceptable: strong docs shell, weak first impression.** | ## Anti-Patterns Verdict diff --git a/.impeccable/critique/2026-07-09T21-58-35Z__docs-index-md.md b/.impeccable/critique/2026-07-09T21-58-35Z__docs-index-md.md index 4b1ae54..332496e 100644 --- a/.impeccable/critique/2026-07-09T21-58-35Z__docs-index-md.md +++ b/.impeccable/critique/2026-07-09T21-58-35Z__docs-index-md.md @@ -6,6 +6,7 @@ p1_count: 1 timestamp: 2026-07-09T21-58-35Z slug: docs-index-md --- + Method: dual-agent (A: 019f48db-2792-7db3-8b40-dfec3def1718 · B: 019f48db-5277-75b1-a137-fa0fdf79d6ce) # DocSlime Homepage Completion Critique @@ -13,7 +14,7 @@ Method: dual-agent (A: 019f48db-2792-7db3-8b40-dfec3def1718 · B: 019f48db-5277- ## Design Health Score | # | Heuristic | Score | Key Issue | -|---|-----------|-------|-----------| +| --- | --- | --- | --- | | 1 | Visibility of System Status | 3 | Static docs page has low status burden; nav and updated timestamp are clear. | | 2 | Match System / Real World | 3 | Developer language fits the audience, though TDD+BDD, DDD, ADR, docmd, and agent skills remain dense for newcomers. | | 3 | User Control and Freedom | 3 | Navigation, search, theme switch, read-next, and install alternatives are present. | @@ -24,7 +25,7 @@ Method: dual-agent (A: 019f48db-2792-7db3-8b40-dfec3def1718 · B: 019f48db-5277- | 8 | Aesthetic and Minimalist Design | 3 | Much less card-grid repetition; residual doc-template rhythm remains. | | 9 | Error Recovery | 2 | Alternate install paths exist, but failed-install recovery guidance is minimal. | | 10 | Help and Documentation | 4 | Strong docs shell, search, TOC, navigation, and follow-up pages. | -| **Total** | | **30/40** | **Good** | +| **Total** | | **30/40** | **Good** | ## Anti-Patterns Verdict @@ -47,25 +48,13 @@ The homepage now works as a DocSlime doorway rather than a default docs article. ## Priority Issues -**[P1] Brand distinctiveness is capped by doc-template rhythm** -Why it matters: DocSlime has an ownable strange/sticky metaphor, but most of the mid-page is still bordered panels, code blocks, and tidy lists. -Fix: If pushing further, make the docs body / absorption / traceability loop a stronger visual system, especially in the `Why It Sticks` section. -Suggested command: `$impeccable overdrive` - -**[P2] Mobile scanability still strains in dense technical sections** -Why it matters: The page is readable on mobile, but the artifact, commands, and acronym-heavy lists create a dense stack. -Fix: Add more progressive disclosure or one compact happy-path block for mobile readers. -Suggested command: `$impeccable adapt` - -**[P2] Install-to-first-run handoff could be sharper** -Why it matters: Homebrew, curl, cargo, `docslime init`, skill install, ADR, and KISS are all present, but a first-timer may still ask which exact sequence is the happy path. -Fix: Add a single recommended path from install to first useful filled doc. -Suggested command: `$impeccable clarify` - -**[P3] Read Next is useful but generic** -Why it matters: The end of the page works, but it does not create much momentum. -Fix: Turn read-next actions into a stronger learning path or “choose your next power” sequence. -Suggested command: `$impeccable delight` +**[P1] Brand distinctiveness is capped by doc-template rhythm** Why it matters: DocSlime has an ownable strange/sticky metaphor, but most of the mid-page is still bordered panels, code blocks, and tidy lists. Fix: If pushing further, make the docs body / absorption / traceability loop a stronger visual system, especially in the `Why It Sticks` section. Suggested command: `$impeccable overdrive` + +**[P2] Mobile scanability still strains in dense technical sections** Why it matters: The page is readable on mobile, but the artifact, commands, and acronym-heavy lists create a dense stack. Fix: Add more progressive disclosure or one compact happy-path block for mobile readers. Suggested command: `$impeccable adapt` + +**[P2] Install-to-first-run handoff could be sharper** Why it matters: Homebrew, curl, cargo, `docslime init`, skill install, ADR, and KISS are all present, but a first-timer may still ask which exact sequence is the happy path. Fix: Add a single recommended path from install to first useful filled doc. Suggested command: `$impeccable clarify` + +**[P3] Read Next is useful but generic** Why it matters: The end of the page works, but it does not create much momentum. Fix: Turn read-next actions into a stronger learning path or “choose your next power” sequence. Suggested command: `$impeccable delight` ## Persona Red Flags diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..ac32087 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,2 @@ +# Prettier does not understand Docmd container directives and collapses their boundaries. +docs/index.md diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..d2504b4 --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,3 @@ +{ + "proseWrap": "never" +} diff --git a/README.md b/README.md index e0c73d7..98ac6a0 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,8 @@ # DocSlime -DocSlime is an opinionated CLI and agent-skill system for turning a repo into a living, -agent-ready documentation workspace. It scaffolds a standardized docs tree that coding -agents can fill in with you, then tighten through skills like `docslime-fill`, -`docslime-adr`, and `docslime-kiss`. +DocSlime is an opinionated CLI and agent-skill system for turning a repo into a living, agent-ready documentation workspace. It scaffolds a standardized docs tree that coding agents can fill in with you, then tighten through skills like `docslime-fill`, `docslime-adr`, and `docslime-kiss`. -The point is to keep a complete product-and-engineering learning loop in the repo: strategy, -product/design context, continuous discovery, requirements, architecture, TDD/BDD evidence, -delivery, observability, and decisions. DocSlime is built for services and user-facing -products with user-driven Domain Driven Design and explicit traceability from evidence to -production learning. +The point is to keep a complete product-and-engineering learning loop in the repo: strategy, product/design context, continuous discovery, requirements, architecture, TDD/BDD evidence, delivery, observability, and decisions. DocSlime is built for services and user-facing products with user-driven Domain Driven Design and explicit traceability from evidence to production learning. ## The tree it creates @@ -33,8 +26,7 @@ docs/ └── README.md # Architecture Decision Record index ``` -`docs/PRODUCT.md` and `docs/DESIGN.md` are intentionally named so tools like `impeccable` -can discover product and design context without a duplicate root-level bridge file. +`docs/PRODUCT.md` and `docs/DESIGN.md` are intentionally named so tools like `impeccable` can discover product and design context without a duplicate root-level bridge file. ## Install @@ -65,23 +57,15 @@ docslime add PRODUCT # add a single document (name resolution is forgiv docslime add adr <slug> # create the next-numbered ADR, e.g. 0001-<slug>.md ``` -Existing files are **never overwritten**. `init` also recognizes the previous numbered -layout and will not create duplicate renamed files beside existing user work. Pass `--force` -to write a current template intentionally; legacy files are still not deleted. +Existing files are **never overwritten**. `init` also recognizes the previous numbered layout and will not create duplicate renamed files beside existing user work. Pass `--force` to write a current template intentionally; legacy files are still not deleted. ### Filling in the docs with an agent -After `docslime init`, point your coding agent at `docs/` and ask it to fill in a document -(start with `PRODUCT.md`). Each file's `<!-- LLM: ... -->` comments tell the agent which -questions to ask you and how to write the section; the agent removes those comments as it -fills each part in. +After `docslime init`, point your coding agent at `docs/` and ask it to fill in a document (start with `PRODUCT.md`). Each file's `<!-- LLM: ... -->` comments tell the agent which questions to ask you and how to write the section; the agent removes those comments as it fills each part in. ## Use with an AI agent (skills) -DocSlime ships a set of [agent skills](.agents/skills) that teach Codex, Claude Code, ChatGPT, -and other skill-aware tools how to drive the whole documentation lifecycle. They are plain -`SKILL.md` folders with `name` / `description` frontmatter, plus `agents/openai.yaml` -metadata for OpenAI/Codex-style interfaces. +DocSlime ships a set of [agent skills](.agents/skills) that teach Codex, Claude Code, ChatGPT, and other skill-aware tools how to drive the whole documentation lifecycle. They are plain `SKILL.md` folders with `name` / `description` frontmatter, plus `agents/openai.yaml` metadata for OpenAI/Codex-style interfaces. Install them with the Skills CLI: @@ -96,22 +80,19 @@ npx skills add DecisionNerd/DocSlime --agent codex npx skills add DecisionNerd/DocSlime --agent claude-code ``` -ChatGPT and Claude Desktop use their own Skills UI / import flows rather than sharing local -project installs automatically, but the same skill folders follow the open Agent Skills -shape and can be reused there. +ChatGPT and Claude Desktop use their own Skills UI / import flows rather than sharing local project installs automatically, but the same skill folders follow the open Agent Skills shape and can be reused there. Then invoke them from inside your AI tool: | Skill | What it does | -|---|---| +| --- | --- | | `docslime-install` | Check the `docslime` binary is installed; install it if missing. | -| `docslime-init` | Scaffold the `docs/` tree into the current repo and orient on what to fill in. | -| `docslime-fill` | Interview you and fill in a document, following its inline `<!-- LLM: ... -->` guidance. | -| `docslime-adr` | Create the next-numbered ADR and fill it in by interviewing you about one decision. | -| `docslime-kiss` | Review docs for bloat, AI slop, weak traceability, and best-practice cleanup. | +| `docslime-init` | Scaffold the `docs/` tree into the current repo and orient on what to fill in. | +| `docslime-fill` | Interview you and fill in a document, following its inline `<!-- LLM: ... -->` guidance. | +| `docslime-adr` | Create the next-numbered ADR and fill it in by interviewing you about one decision. | +| `docslime-kiss` | Review docs for bloat, AI slop, weak traceability, and best-practice cleanup. | -A typical first run: `/docslime-install` → `/docslime-init` → `/docslime-fill` starting with -`PRODUCT.md`, then `/docslime-kiss` once docs are filled enough to tighten. +A typical first run: `/docslime-install` → `/docslime-init` → `/docslime-fill` starting with `PRODUCT.md`, then `/docslime-kiss` once docs are filled enough to tighten. ## Development @@ -123,22 +104,13 @@ npm run build # build the docmd site from docs/ cargo build --release # optimized binary at target/release/docslime ``` -The templates live in [`templates/`](templates/) (the `init` tree) and -[`assets/adr.md`](assets/adr.md) (the single-record ADR template). They are embedded into the -binary at compile time via [`include_dir`], so editing a template requires a rebuild. +The templates live in [`templates/`](templates/) (the `init` tree) and [`assets/adr.md`](assets/adr.md) (the single-record ADR template). They are embedded into the binary at compile time via [`include_dir`], so editing a template requires a rebuild. -This repo is a small monorepo: the Rust CLI, the `docmd.io` site, and the bundled agent -skills ship from the same checkout. `.github/workflows/ci.yml` keeps those surfaces explicit -with `CLI`, `Site`, and `Agent skills` jobs, plus a branch-policy check that allows only -`staging` to open pull requests to `main`; feature branches target `staging`. +This repo is a small monorepo: the Rust CLI, the `docmd.io` site, and the bundled agent skills ship from the same checkout. `.github/workflows/ci.yml` keeps those surfaces explicit with `CLI`, `Site`, and `Agent skills` jobs, plus a branch-policy check that allows only `staging` to open pull requests to `main`; feature branches target `staging`. ## Releasing -Distribution is configured for [`cargo-dist`] in `Cargo.toml` (`[workspace.metadata.dist]`). -The release workflow runs when a SemVer tag such as `v0.3.0` is pushed. It builds the -macOS/Linux binaries, publishes a GitHub Release with the install script, pushes the -Homebrew formula to `DecisionNerd/homebrew-tap` using `HOMEBREW_TAP_TOKEN`, and keeps the -documentation content ready for publication through the `docmd.io` system. +Distribution is configured for [`cargo-dist`] in `Cargo.toml` (`[workspace.metadata.dist]`). The release workflow runs when a SemVer tag such as `v0.3.0` is pushed. It builds the macOS/Linux binaries, publishes a GitHub Release with the install script, pushes the Homebrew formula to `DecisionNerd/homebrew-tap` using `HOMEBREW_TAP_TOKEN`, and keeps the documentation content ready for publication through the `docmd.io` system. Release checklist: diff --git a/assets/adr.md b/assets/adr.md index ea74a5a..a631d71 100644 --- a/assets/adr.md +++ b/assets/adr.md @@ -1,8 +1,4 @@ -<!-- LLM: This is a single Architecture Decision Record. Fill it in by interviewing the user -about ONE decision. Keep it focused — one ADR, one decision. Once accepted, treat it as -immutable: to revisit the decision, create a new ADR that supersedes this one. Update the -`Status` and `Date`, then add a row to ../README.md's decision log. Remove LLM comments as -you complete each section. --> +<!-- LLM: This is a single Architecture Decision Record. Fill it in by interviewing the user about ONE decision. Keep it focused — one ADR, one decision. Once accepted, treat it as immutable: to revisit the decision, create a new ADR that supersedes this one. Update the `Status` and `Date`, then add a row to ../README.md's decision log. Remove LLM comments as you complete each section. --> # ADR-NNNN: TITLE @@ -12,38 +8,33 @@ you complete each section. --> ## Context -<!-- LLM: Describe the forces at play — the problem, constraints, and requirements that make a -decision necessary. Ask the user: "What situation are we in that forces a choice? What -requirements or constraints bound it?" Reference the relevant requirement IDs from -../../REQUIREMENTS.md where applicable. State facts, not the decision yet. --> +<!-- LLM: Describe the forces at play — the problem, constraints, and requirements that make a decision necessary. Ask the user: "What situation are we in that forces a choice? What requirements or constraints bound it?" Reference the relevant requirement IDs from ../../REQUIREMENTS.md where applicable. State facts, not the decision yet. --> _What is the issue we're deciding on, and why now?_ ## Options considered -<!-- LLM: List the realistic alternatives, each with its pros and cons. Ask the user what -options were on the table — including "do nothing". A decision with only one option recorded -is a red flag; probe for the alternatives that were rejected. --> +<!-- LLM: List the realistic alternatives, each with its pros and cons. Ask the user what options were on the table — including "do nothing". A decision with only one option recorded is a red flag; probe for the alternatives that were rejected. --> ### Option A — _name_ + - **Pros:** _…_ - **Cons:** _…_ ### Option B — _name_ + - **Pros:** _…_ - **Cons:** _…_ ## Decision -<!-- LLM: State the option chosen, clearly and in the active voice ("We will …"). Then give -the rationale: why this option won over the others. --> +<!-- LLM: State the option chosen, clearly and in the active voice ("We will …"). Then give the rationale: why this option won over the others. --> _We will … because …_ ## Consequences -<!-- LLM: Capture what becomes easier and what becomes harder as a result — positive, -negative, and neutral. Note any follow-up work or new risks this decision introduces. --> +<!-- LLM: Capture what becomes easier and what becomes harder as a result — positive, negative, and neutral. Note any follow-up work or new risks this decision introduces. --> - **Positive:** _…_ - **Negative:** _…_ diff --git a/docs/experience/README.md b/docs/experience/README.md index 2d2bfc9..ca8144a 100644 --- a/docs/experience/README.md +++ b/docs/experience/README.md @@ -43,15 +43,25 @@ Create one focused lowercase-kebab-case file when an opportunity, study, journey # Opportunity or experience ## Observed need and evidence + ## Desired user and business outcome + ## Users and context + ## Current journey + ## Opportunity and hypothesis + ## Intended behavior + ## Given / When / Then scenarios + ## Constraints and domain language + ## Success signals and telemetry + ## Open questions + ## Related requirements, tests, architecture, and ADRs ``` diff --git a/package-lock.json b/package-lock.json index 677e28c..d70a7f1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,6 +9,9 @@ "version": "0.3.0", "dependencies": { "@docmd/core": "^0.8.10" + }, + "devDependencies": { + "prettier": "3.6.2" } }, "node_modules/@docmd/api": { @@ -1185,6 +1188,22 @@ "integrity": "sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==", "license": "MIT" }, + "node_modules/prettier": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz", + "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==", + "dev": true, + "license": "MIT", + "bin": { + "prettier": "bin/prettier.cjs" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, "node_modules/punycode.js": { "version": "2.3.1", "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", diff --git a/package.json b/package.json index 6801f3a..9ebe48f 100644 --- a/package.json +++ b/package.json @@ -5,10 +5,15 @@ "type": "module", "scripts": { "dev": "docmd dev", - "build": "docmd build && node scripts/check-rendered-line-breaks.mjs", + "build": "npm run check:markdown && docmd build && node scripts/check-rendered-line-breaks.mjs", + "format:markdown": "prettier --write \"**/*.md\" && node scripts/format-markdown-comments.mjs", + "check:markdown": "prettier --check \"**/*.md\" && node scripts/format-markdown-comments.mjs --check", "preview": "npx serve site" }, "dependencies": { "@docmd/core": "^0.8.10" + }, + "devDependencies": { + "prettier": "3.6.2" } } diff --git a/scripts/format-markdown-comments.mjs b/scripts/format-markdown-comments.mjs new file mode 100644 index 0000000..f749561 --- /dev/null +++ b/scripts/format-markdown-comments.mjs @@ -0,0 +1,73 @@ +import { execFileSync } from "node:child_process"; +import { readFile, writeFile } from "node:fs/promises"; + +const checkOnly = process.argv.includes("--check"); +const markdownFiles = execFileSync("git", ["ls-files", "-z", "--", "*.md"], { encoding: "utf8" }) + .split("\0") + .filter(Boolean); +const changed = []; + +function formatComment(match, body) { + if (!body.includes("\n")) return match; + + const sourceLines = body + .split("\n") + .map((line) => line.trim()) + .filter(Boolean); + const output = []; + let paragraph = ""; + let listItem = ""; + + const flushParagraph = () => { + if (paragraph) output.push(paragraph); + paragraph = ""; + }; + const flushListItem = () => { + if (listItem) output.push(listItem); + listItem = ""; + }; + + for (const line of sourceLines) { + if (/^(?:[-*+] |\d+[.)] )/.test(line)) { + flushParagraph(); + flushListItem(); + listItem = line; + continue; + } + + if (listItem) { + if (/^[a-z0-9_`([{"']/.test(line)) { + listItem += ` ${line}`; + continue; + } + flushListItem(); + } + + paragraph = paragraph ? `${paragraph} ${line}` : line; + } + + flushListItem(); + flushParagraph(); + return `<!-- ${output.join("\n")} -->`; +} + +for (const file of markdownFiles) { + const source = await readFile(file, "utf8"); + const formatted = source.replace(/<!--([\s\S]*?)-->/g, formatComment); + + if (formatted === source) continue; + changed.push(file); + if (!checkOnly) await writeFile(file, formatted); +} + +if (checkOnly && changed.length > 0) { + console.error("Markdown comments contain line-length wrapping:"); + for (const file of changed) console.error(`- ${file}`); + process.exit(1); +} + +if (checkOnly) { + console.log("Verified Markdown comments have no line-length wrapping."); +} else { + for (const file of changed) console.log(file); +} diff --git a/templates/DESIGN.md b/templates/DESIGN.md index cb88512..7e12225 100644 --- a/templates/DESIGN.md +++ b/templates/DESIGN.md @@ -1,39 +1,26 @@ -<!-- LLM: This document captures the product's design context: brand, content, interaction, -accessibility, and component conventions that make the experience coherent. It is also -discoverable by tools that look for DESIGN.md. Read PRODUCT.md and relevant evidence in -experience/ first. -Interview the user about any existing brand, UI kit, design system, Storybook, tokens, -screenshots, Figma files, terminal conventions, docs standards, or accessibility bar. Keep -implementation mechanics in engineering/ unless they are necessary to explain a design -rule. Remove LLM comments as you go. --> +<!-- LLM: This document captures the product's design context: brand, content, interaction, accessibility, and component conventions that make the experience coherent. It is also discoverable by tools that look for DESIGN.md. Read PRODUCT.md and relevant evidence in experience/ first. Interview the user about any existing brand, UI kit, design system, Storybook, tokens, screenshots, Figma files, terminal conventions, docs standards, or accessibility bar. Keep implementation mechanics in engineering/ unless they are necessary to explain a design rule. Remove LLM comments as you go. --> # Design -<!-- LLM: One short paragraph. Describe the role this design context plays for the project. -For services or CLIs, cover terminal/docs/API experience. For user-facing products, cover -visual and interaction experience too. --> +<!-- LLM: One short paragraph. Describe the role this design context plays for the project. For services or CLIs, cover terminal/docs/API experience. For user-facing products, cover visual and interaction experience too. --> _What should stay consistent across the product experience?_ ## Design Principles -<!-- LLM: Capture 3-6 principles that guide product decisions and UX trade-offs. These should -connect to evidence and hypotheses in experience/. --> +<!-- LLM: Capture 3-6 principles that guide product decisions and UX trade-offs. These should connect to evidence and hypotheses in experience/. --> - **_Principle name_** - _what it means in practice._ ## Design tool context -<!-- LLM: Explain how design-aware agents or tools should use this file. If the project uses -impeccable, Figma, Storybook, screenshots, or another source of visual truth, link it here. -Keep this section about context and workflow, not implementation detail. --> +<!-- LLM: Explain how design-aware agents or tools should use this file. If the project uses impeccable, Figma, Storybook, screenshots, or another source of visual truth, link it here. Keep this section about context and workflow, not implementation detail. --> _How should design critique or UI iteration use PRODUCT.md and DESIGN.md?_ ## Brand And Voice -<!-- LLM: Document naming, tone, writing style, terminology, and visible personality. Include -words to use/avoid when that matters. --> +<!-- LLM: Document naming, tone, writing style, terminology, and visible personality. Include words to use/avoid when that matters. --> - **Tone:** _how the product should sound._ - **Terminology:** _preferred words and names._ @@ -41,10 +28,7 @@ words to use/avoid when that matters. --> ## Visual And Content Style -<!-- LLM: Capture visual/content rules that apply to the product. If the project has no -visual UI, state what is not applicable and document terminal, API, docs, or generated -artifact style instead. Use Mermaid fenced blocks for flowcharts rather than ASCII art. -Link to tokens, CSS, Figma, brand assets, or Storybook when available. --> +<!-- LLM: Capture visual/content rules that apply to the product. If the project has no visual UI, state what is not applicable and document terminal, API, docs, or generated artifact style instead. Use Mermaid fenced blocks for flowcharts rather than ASCII art. Link to tokens, CSS, Figma, brand assets, or Storybook when available. --> - **Color:** _palette, semantic usage, contrast expectations._ - **Typography:** _font choices, scale, hierarchy._ @@ -54,8 +38,7 @@ Link to tokens, CSS, Figma, brand assets, or Storybook when available. --> ## Interaction Patterns -<!-- LLM: Document common interaction rules: navigation, forms, loading, empty/error/success -states, keyboard behavior, CLI output, API ergonomics, motion, and progressive disclosure. --> +<!-- LLM: Document common interaction rules: navigation, forms, loading, empty/error/success states, keyboard behavior, CLI output, API ergonomics, motion, and progressive disclosure. --> - **Navigation:** _how users move through the product._ - **Controls:** _buttons, inputs, menus, toggles, commands, or API calls._ @@ -64,23 +47,20 @@ states, keyboard behavior, CLI output, API ergonomics, motion, and progressive d ## Components And Patterns -<!-- LLM: List reusable components, UI patterns, command patterns, API patterns, or docs -patterns. Link to code, Storybook, design files, or implementation docs where they exist. --> +<!-- LLM: List reusable components, UI patterns, command patterns, API patterns, or docs patterns. Link to code, Storybook, design files, or implementation docs where they exist. --> -| Component / pattern | Use it for | Notes / source | -|---|---|---| -| _Name_ | _When to use it_ | _Link or rule_ | +| Component / pattern | Use it for | Notes / source | +| ------------------- | ---------------- | -------------- | +| _Name_ | _When to use it_ | _Link or rule_ | ## Accessibility -<!-- LLM: Capture the accessibility bar. Include keyboard behavior, focus, contrast, reduced -motion, semantic HTML, screen-reader expectations, CLI equivalents, or docs accessibility. --> +<!-- LLM: Capture the accessibility bar. Include keyboard behavior, focus, contrast, reduced motion, semantic HTML, screen-reader expectations, CLI equivalents, or docs accessibility. --> - _Accessibility rule or target._ ## References -<!-- LLM: Link the source of truth for design assets and implementation surfaces. Delete this -section if there are no references yet. --> +<!-- LLM: Link the source of truth for design assets and implementation surfaces. Delete this section if there are no references yet. --> - _Figma / Storybook / token file / component directory / brand asset._ diff --git a/templates/PRODUCT.md b/templates/PRODUCT.md index 142345a..e22dbdb 100644 --- a/templates/PRODUCT.md +++ b/templates/PRODUCT.md @@ -1,8 +1,4 @@ -<!-- LLM: This is the foundation product-context document. It is also discoverable by tools -that look for PRODUCT.md. Interview the user before writing. Work through the sections in -order, asking one focused question at a time and reflecting their answers back. Keep the -final document tight: this is the source of product truth, not a feature backlog. Remove each -LLM comment once its section is filled. --> +<!-- LLM: This is the foundation product-context document. It is also discoverable by tools that look for PRODUCT.md. Interview the user before writing. Work through the sections in order, asking one focused question at a time and reflecting their answers back. Keep the final document tight: this is the source of product truth, not a feature backlog. Remove each LLM comment once its section is filled. --> # Product @@ -26,9 +22,7 @@ _What problem are we solving, and for whom?_ ## Audience -<!-- LLM: Identify primary and secondary users, buyers, operators, admins, integrators, or -dependent teams. For each, capture what they need from the product and what "good" feels -like to them. Link to experience/ when fuller personas or journeys exist. --> +<!-- LLM: Identify primary and secondary users, buyers, operators, admins, integrators, or dependent teams. For each, capture what they need from the product and what "good" feels like to them. Link to experience/ when fuller personas or journeys exist. --> - _Audience / role - need_ @@ -43,8 +37,7 @@ _Where are we headed?_ ## Goals -<!-- LLM: List the concrete outcomes that define success. Ask the user for 3-5 goals. -Each should be an outcome, not a feature. Prefer measurable where possible. --> +<!-- LLM: List the concrete outcomes that define success. Ask the user for 3-5 goals. Each should be an outcome, not a feature. Prefer measurable where possible. --> - _Goal 1_ - _Goal 2_ @@ -52,33 +45,26 @@ Each should be an outcome, not a feature. Prefer measurable where possible. --> ## Quality stance -<!-- LLM: Capture the project's quality method. Ask whether the project uses TDD, BDD, -Domain Driven Design, ADRs, design critique, security review, or other quality gates. Keep -this as product-level stance; put concrete test mappings in `engineering/TESTING.md`, -production measures in `engineering/OBSERVABILITY.md`, and decisions in ADRs. --> +<!-- LLM: Capture the project's quality method. Ask whether the project uses TDD, BDD, Domain Driven Design, ADRs, design critique, security review, or other quality gates. Keep this as product-level stance; put concrete test mappings in `engineering/TESTING.md`, production measures in `engineering/OBSERVABILITY.md`, and decisions in ADRs. --> - _Quality method / gate - why it matters_ ## Non-goals -<!-- LLM: Explicitly list what this project will NOT do. This prevents scope creep and is -often as valuable as the goals. Ask: "What might people assume this does that it deliberately -won't?" --> +<!-- LLM: Explicitly list what this project will NOT do. This prevents scope creep and is often as valuable as the goals. Ask: "What might people assume this does that it deliberately won't?" --> - _Non-goal 1_ - _Non-goal 2_ ## Success Metrics -<!-- LLM: How will we know the product is fulfilling its mission? Ask for the few signals or -metrics that would tell the team it's working. Tie each back to a goal above where possible. --> +<!-- LLM: How will we know the product is fulfilling its mission? Ask for the few signals or metrics that would tell the team it's working. Tie each back to a goal above where possible. --> - _Metric 1_ - _Metric 2_ ## Stakeholders -<!-- LLM: Who cares about this project and in what role (owner, users, sponsors, dependents)? -Keep it brief. Remove this section if the user says it's not relevant. --> +<!-- LLM: Who cares about this project and in what role (owner, users, sponsors, dependents)? Keep it brief. Remove this section if the user says it's not relevant. --> - _Role - who / why_ diff --git a/templates/README.md b/templates/README.md index a0ddc4a..613e860 100644 --- a/templates/README.md +++ b/templates/README.md @@ -1,34 +1,21 @@ -<!-- LLM: This is the entry point to the project's documentation. Keep it short and -navigational. Do NOT interview the user for this file first — fill it in last, once the -other docs exist, so the descriptions match what was actually written. Remove LLM comments -as you complete each section. --> +<!-- LLM: This is the entry point to the project's documentation. Keep it short and navigational. Do NOT interview the user for this file first — fill it in last, once the other docs exist, so the descriptions match what was actually written. Remove LLM comments as you complete each section. --> # Documentation -This folder holds the living documentation for this project. Product and design context -feed continuous discovery, requirements translate that evidence into a build contract, and -engineering docs carry the contract through architecture, testing, publishing, and -production observability. The docs stay in-repo so people and coding agents can work from -the same evidence without reaching for an external source. +This folder holds the living documentation for this project. Product and design context feed continuous discovery, requirements translate that evidence into a build contract, and engineering docs carry the contract through architecture, testing, publishing, and production observability. The docs stay in-repo so people and coding agents can work from the same evidence without reaching for an external source. ## Adapt this template to the project -This tree is a broad starting template, not a compliance checklist. Keep the documents that -help this project's humans or agents make better decisions; remove, merge, or replace the -rest with links to authoritative organization-level context. Update this index and affected -links whenever the shape changes. +This tree is a broad starting template, not a compliance checklist. Keep the documents that help this project's humans or agents make better decisions; remove, merge, or replace the rest with links to authoritative organization-level context. Update this index and affected links whenever the shape changes. -For example, a backend API service in a large organization may not need local product -strategy or visual design docs when those concerns are owned elsewhere. It may still keep -`experience/` to document developer experience (DX), operator and integration journeys, and -agent experience for coding agents or other automated consumers of the service. +For example, a backend API service in a large organization may not need local product strategy or visual design docs when those concerns are owned elsewhere. It may still keep `experience/` to document developer experience (DX), operator and integration journeys, and agent experience for coding agents or other automated consumers of the service. ## How the docs are organized Follow this lifecycle rather than treating the filenames as a numbered checklist: | Document | Question it answers | -|---|---| +| --- | --- | | [`PRODUCT.md`](PRODUCT.md) | What is this product, who is it for, and why does it exist? | | [`DESIGN.md`](DESIGN.md) | What should stay consistent in product, docs, and UX experience? | | [`experience/`](experience/) | What have we learned from users, and what outcomes and behaviors do they need? | @@ -41,7 +28,7 @@ Follow this lifecycle rather than treating the filenames as a numbered checklist Supporting detail lives in subfolders: | Folder | Contents | -|---|---| +| --- | --- | | [`strategy/`](strategy/) | Market, positioning, business model, roadmap, and strategic bets. | | [`experience/`](experience/) | Continuous discovery, research, opportunities, journeys, hypotheses, and behavior scenarios. | | [`engineering/`](engineering/) | Architecture, CI, delivery, observability, operations, and decision records. | @@ -51,13 +38,8 @@ Supporting detail lives in subfolders: - **Keep docs current.** When behavior changes, update the doc in the same change. - **Link, don't duplicate.** Reference detail in subfolders rather than copying it. -- **Trace evidence through delivery.** User evidence should lead to requirements, tests, - architecture, telemetry, and production learning. +- **Trace evidence through delivery.** User evidence should lead to requirements, tests, architecture, telemetry, and production learning. - **Decisions are recorded.** Significant choices get an ADR (see `engineering/adrs/`). -- **Keep applicable context discoverable.** When retained, `PRODUCT.md` and `DESIGN.md` stay - in `docs/` so design and coding agents can load them without duplicate root files. -- **Close the loop.** Observability should measure both system health and the user outcomes - named in product, experience, and requirements docs. -- **Choose release conventions intentionally.** Consider Semantic Versioning and Conventional - Commits when they clarify compatibility and change intent, but preserve a team's effective - existing workflow and add enforcement only with explicit agreement. +- **Keep applicable context discoverable.** When retained, `PRODUCT.md` and `DESIGN.md` stay in `docs/` so design and coding agents can load them without duplicate root files. +- **Close the loop.** Observability should measure both system health and the user outcomes named in product, experience, and requirements docs. +- **Choose release conventions intentionally.** Consider Semantic Versioning and Conventional Commits when they clarify compatibility and change intent, but preserve a team's effective existing workflow and add enforcement only with explicit agreement. diff --git a/templates/REQUIREMENTS.md b/templates/REQUIREMENTS.md index 36ac370..8f0b9ea 100644 --- a/templates/REQUIREMENTS.md +++ b/templates/REQUIREMENTS.md @@ -1,70 +1,52 @@ -<!-- LLM: This document is the shared contract between intent and engineering. Translate -evidence from retained local docs, experience/, and linked authoritative context into concrete, -checkable requirements without repeating personas, journeys, research, or proposed -architecture. Give every requirement a stable ID so architecture, tests, ADRs, publishing, -and observability can reference it. Capture acceptance behavior in Given/When/Then language -when it clarifies the observable outcome. Remove LLM comments as you complete each section. --> +<!-- LLM: This document is the shared contract between intent and engineering. Translate evidence from retained local docs, experience/, and linked authoritative context into concrete, checkable requirements without repeating personas, journeys, research, or proposed architecture. Give every requirement a stable ID so architecture, tests, ADRs, publishing, and observability can reference it. Capture acceptance behavior in Given/When/Then language when it clarifies the observable outcome. Remove LLM comments as you complete each section. --> # Requirements <!-- LLM: One-paragraph summary of the scope these requirements cover. --> -_What must the delivered system demonstrably do, and which user or business outcomes does -that contract serve?_ +_What must the delivered system demonstrably do, and which user or business outcomes does that contract serve?_ ## Functional requirements -<!-- LLM: The behaviors the system must exhibit. Interview the user, then write each as a -single testable "the system shall..." statement with a stable ID. Group by area if helpful. -Link each back to the experience it serves. Ask probing questions: inputs, outputs, edge -cases, error handling, permissions. --> +<!-- LLM: The behaviors the system must exhibit. Interview the user, then write each as a single testable "the system shall..." statement with a stable ID. Group by area if helpful. Link each back to the experience it serves. Ask probing questions: inputs, outputs, edge cases, error handling, permissions. --> | ID | Requirement | Derived from | Acceptance behavior | -|---|---|---|---| +| --- | --- | --- | --- | | FR-1 | _The system shall …_ | _experience/file.md / product goal_ | _Given … When … Then …_ | | FR-2 | _The system shall …_ | _experience/file.md / product goal_ | _Observable outcome_ | ## Non-functional requirements -<!-- LLM: Qualities and constraints rather than behaviors — performance, reliability, -security, accessibility, portability, cost. Ask the user for concrete targets where possible -("responds within Xms", "runs offline", "supports macOS and Linux"). --> +<!-- LLM: Qualities and constraints rather than behaviors — performance, reliability, security, accessibility, portability, cost. Ask the user for concrete targets where possible ("responds within Xms", "runs offline", "supports macOS and Linux"). --> | ID | Quality attribute | Target / constraint | Why it matters | -|---|---|---|---| +| --- | --- | --- | --- | | NFR-1 | _Performance / reliability / security / accessibility / …_ | _Measurable target_ | _User, design, operational, or regulatory reason_ | | NFR-2 | _…_ | _…_ | _…_ | ## Behavior trace -<!-- LLM: Optional but strongly recommended for behavior-heavy projects. Capture the small -set of BDD scenarios that prove the highest-value requirements. Link back to the discovery -artifact rather than duplicating its narrative, and expand the scenarios into concrete tests -in engineering/TESTING.md. Remove this section if it adds no value. --> +<!-- LLM: Optional but strongly recommended for behavior-heavy projects. Capture the small set of BDD scenarios that prove the highest-value requirements. Link back to the discovery artifact rather than duplicating its narrative, and expand the scenarios into concrete tests in engineering/TESTING.md. Remove this section if it adds no value. --> | Requirement | Given | When | Then | -|---|---|---|---| +| --- | --- | --- | --- | | _FR-1_ | _initial context_ | _user/system action_ | _observable outcome_ | ## Constraints & assumptions -<!-- LLM: Capture fixed constraints (tech, regulatory, timeline, budget) and assumptions the -requirements rely on. Ask: "What is non-negotiable? What are we taking for granted that, if -wrong, would change these requirements?" --> +<!-- LLM: Capture fixed constraints (tech, regulatory, timeline, budget) and assumptions the requirements rely on. Ask: "What is non-negotiable? What are we taking for granted that, if wrong, would change these requirements?" --> - **Constraint:** _…_ - **Assumption:** _…_ ## Dependencies -<!-- LLM: External systems, services, libraries, or teams this depends on. Note anything that -could block delivery. Remove if none. --> +<!-- LLM: External systems, services, libraries, or teams this depends on. Note anything that could block delivery. Remove if none. --> - _Dependency — why it matters_ ## Open questions -<!-- LLM: Track unresolved requirement questions here rather than guessing. Each should name -who needs to answer it. Clear them as they're resolved. --> +<!-- LLM: Track unresolved requirement questions here rather than guessing. Each should name who needs to answer it. Clear them as they're resolved. --> - _Question — owner_ diff --git a/templates/engineering/ARCHITECTURE.md b/templates/engineering/ARCHITECTURE.md index bbac6cb..6f7d0b0 100644 --- a/templates/engineering/ARCHITECTURE.md +++ b/templates/engineering/ARCHITECTURE.md @@ -1,23 +1,14 @@ -<!-- LLM: This document explains how the system is designed to meet the requirements -(../REQUIREMENTS.md). Read the prior docs first so the architecture clearly serves the -requirements and experience evidence. Interview the user about the actual or intended design — don't -invent components. Where a significant choice was made between alternatives, record it as an -ADR in adrs/ and link to it here rather than arguing the decision inline. -Remove LLM comments as you fill each section. --> +<!-- LLM: This document explains how the system is designed to meet the requirements (../REQUIREMENTS.md). Read the prior docs first so the architecture clearly serves the requirements and experience evidence. Interview the user about the actual or intended design — don't invent components. Where a significant choice was made between alternatives, record it as an ADR in adrs/ and link to it here rather than arguing the decision inline. Remove LLM comments as you fill each section. --> # Architecture -<!-- LLM: One-paragraph overview of the system shape (e.g. "a single-binary CLI", "a web app -with a Postgres backend"). Give the reader the mental model before the detail. --> +<!-- LLM: One-paragraph overview of the system shape (e.g. "a single-binary CLI", "a web app with a Postgres backend"). Give the reader the mental model before the detail. --> _What kind of system is this, in one paragraph?_ ## Context diagram -<!-- LLM: Show the system in its environment — its users and the external systems it talks to. -A Mermaid flowchart is the standard for relationships and flows; do not use ASCII art. If the -relationships do not merit a diagram, use concise prose or a bullet list instead. Ask the user -what's inside the boundary vs. outside it. --> +<!-- LLM: Show the system in its environment — its users and the external systems it talks to. A Mermaid flowchart is the standard for relationships and flows; do not use ASCII art. If the relationships do not merit a diagram, use concise prose or a bullet list instead. Ask the user what's inside the boundary vs. outside it. --> ```mermaid flowchart LR @@ -27,38 +18,29 @@ flowchart LR ## Components -<!-- LLM: Break the system into its major parts. For each, state its single responsibility and -what it depends on. Ask the user to walk through the pieces; capture one row per component. -Keep responsibilities crisp — if a component does "everything", probe to split it. --> +<!-- LLM: Break the system into its major parts. For each, state its single responsibility and what it depends on. Ask the user to walk through the pieces; capture one row per component. Keep responsibilities crisp — if a component does "everything", probe to split it. --> -| Component | Responsibility | Depends on | -|---|---|---| -| _Name_ | _What it owns_ | _Other components / services_ | +| Component | Responsibility | Depends on | +| --------- | -------------- | ----------------------------- | +| _Name_ | _What it owns_ | _Other components / services_ | ## Data model -<!-- LLM: Describe the key entities and their relationships, or the main data structures / -state. Link to a schema file if one exists. Ask: "What are the nouns the system stores or -passes around, and how do they relate?" Remove if the system is essentially stateless. --> +<!-- LLM: Describe the key entities and their relationships, or the main data structures / state. Link to a schema file if one exists. Ask: "What are the nouns the system stores or passes around, and how do they relate?" Remove if the system is essentially stateless. --> _Key entities and relationships._ ## Domain language and boundaries -<!-- LLM: Use Domain Driven Design lightly. Ask: "What are the core domain nouns, what words -must mean one thing here, and where are the boundaries between responsibilities?" Capture -bounded contexts only when they clarify the system. If there is no meaningful domain split, -say so and remove the table. --> +<!-- LLM: Use Domain Driven Design lightly. Ask: "What are the core domain nouns, what words must mean one thing here, and where are the boundaries between responsibilities?" Capture bounded contexts only when they clarify the system. If there is no meaningful domain split, say so and remove the table. --> | Domain concept | Meaning in this project | Boundary / owner | -|---|---|---| +| --- | --- | --- | | _Concept_ | _Definition in project language_ | _Component, team, module, or external system_ | ## Key flows -<!-- LLM: Trace 1-3 important paths through the system end-to-end (e.g. the main request, the -main command). Number the steps and name the components involved. These should line up with -the relevant requirements and evidence in ../experience/. --> +<!-- LLM: Trace 1-3 important paths through the system end-to-end (e.g. the main request, the main command). Number the steps and name the components involved. These should line up with the relevant requirements and evidence in ../experience/. --> ### _Flow name_ @@ -67,9 +49,7 @@ the relevant requirements and evidence in ../experience/. --> ## Cross-cutting concerns -<!-- LLM: How the design handles concerns that span components: error handling, logging, -configuration, auth/security, performance, observability. Ask the user which of these apply -and how they're addressed. Drop the ones that don't apply. --> +<!-- LLM: How the design handles concerns that span components: error handling, logging, configuration, auth/security, performance, observability. Ask the user which of these apply and how they're addressed. Drop the ones that don't apply. --> - **Error handling:** _…_ - **Configuration:** _…_ @@ -78,15 +58,12 @@ and how they're addressed. Drop the ones that don't apply. --> ## Decisions -<!-- LLM: List the significant architectural decisions, each linking to its ADR. Do not -re-argue them here. If no ADRs exist yet, prompt the user: "What were the big either/or -choices? Each deserves an ADR." Use `docslime add adr <slug>` to create one. --> +<!-- LLM: List the significant architectural decisions, each linking to its ADR. Do not re-argue them here. If no ADRs exist yet, prompt the user: "What were the big either/or choices? Each deserves an ADR." Use `docslime add adr <slug>` to create one. --> - _[ADR-0001 — short title](adrs/0001-*.md)_ ## Risks & trade-offs -<!-- LLM: Capture where the design is knowingly weak or where a trade-off was accepted, and -why. Honest risk-listing here saves pain later. --> +<!-- LLM: Capture where the design is knowingly weak or where a trade-off was accepted, and why. Honest risk-listing here saves pain later. --> - _Risk / trade-off — mitigation or rationale_ diff --git a/templates/engineering/OBSERVABILITY.md b/templates/engineering/OBSERVABILITY.md index 02a37cd..08d2224 100644 --- a/templates/engineering/OBSERVABILITY.md +++ b/templates/engineering/OBSERVABILITY.md @@ -1,38 +1,28 @@ -<!-- LLM: This document defines how the team knows the product works in production. Read -the applicable retained docs: ../PRODUCT.md when present, ../REQUIREMENTS.md, relevant -experience artifacts, ARCHITECTURE.md, and -PUBLISHING.md first. Cover both system health and user outcomes; logs and uptime alone are -not enough. Interview the user about actual telemetry, ownership, privacy, alerting, and the -feedback loop into continuous discovery. Remove LLM comments as you complete each section. --> +<!-- LLM: This document defines how the team knows the product works in production. Read the applicable retained docs: ../PRODUCT.md when present, ../REQUIREMENTS.md, relevant experience artifacts, ARCHITECTURE.md, and PUBLISHING.md first. Cover both system health and user outcomes; logs and uptime alone are not enough. Interview the user about actual telemetry, ownership, privacy, alerting, and the feedback loop into continuous discovery. Remove LLM comments as you complete each section. --> # Observability -_How do we know the system is healthy, users are succeeding, and our product hypotheses are -true in production?_ +_How do we know the system is healthy, users are succeeding, and our product hypotheses are true in production?_ ## Observable outcomes -<!-- LLM: Connect product goals, experience hypotheses, and requirements to production -signals. Distinguish a technical signal from the user or business outcome it proxies. --> +<!-- LLM: Connect product goals, experience hypotheses, and requirements to production signals. Distinguish a technical signal from the user or business outcome it proxies. --> | Outcome / requirement | Signal | Source | Expected range | Owner | -|---|---|---|---|---| +| --- | --- | --- | --- | --- | | _Goal, hypothesis, FR/NFR_ | _Event, metric, trace, log, feedback_ | _System/tool_ | _Target or baseline_ | _Role/team_ | ## Service health -<!-- LLM: Define SLIs/SLOs and critical dependencies with measurable targets. Include -availability, latency, correctness, freshness, saturation, or cost only where relevant. --> +<!-- LLM: Define SLIs/SLOs and critical dependencies with measurable targets. Include availability, latency, correctness, freshness, saturation, or cost only where relevant. --> -| Service / journey | Indicator | Objective | Window | -|---|---|---|---| -| _Name_ | _SLI_ | _SLO_ | _Period_ | +| Service / journey | Indicator | Objective | Window | +| ----------------- | --------- | --------- | -------- | +| _Name_ | _SLI_ | _SLO_ | _Period_ | ## Telemetry design -<!-- LLM: Document the event taxonomy and logs/metrics/traces needed to explain important -journeys and failures. Link event names back to requirements and domain language. State -sampling, retention, correlation, and cardinality rules where they matter. --> +<!-- LLM: Document the event taxonomy and logs/metrics/traces needed to explain important journeys and failures. Link event names back to requirements and domain language. State sampling, retention, correlation, and cardinality rules where they matter. --> - **Events:** _User-visible outcomes and product-learning signals._ - **Logs:** _Structured diagnostic facts and correlation identifiers._ @@ -41,24 +31,20 @@ sampling, retention, correlation, and cardinality rules where they matter. --> ## Dashboards and alerts -<!-- LLM: Name the dashboards people actually use. Alerts must be actionable: identify the -owner, trigger, severity, and response. Avoid alerting on symptoms no one can act on. --> +<!-- LLM: Name the dashboards people actually use. Alerts must be actionable: identify the owner, trigger, severity, and response. Avoid alerting on symptoms no one can act on. --> | Signal | Trigger | Severity | Owner | Response | -|---|---|---|---|---| +| --- | --- | --- | --- | --- | | _Signal_ | _Threshold or anomaly_ | _Level_ | _Role/team_ | _Runbook or action_ | ## Privacy and safety -<!-- LLM: Capture consent, sensitive-data exclusions, access controls, retention, deletion, -and regional constraints. Observability must not create a shadow user-data store. --> +<!-- LLM: Capture consent, sensitive-data exclusions, access controls, retention, deletion, and regional constraints. Observability must not create a shadow user-data store. --> - _Privacy, security, or compliance rule._ ## Production learning loop -<!-- LLM: Explain how production evidence reaches product and design work. Name the review -cadence, participants, thresholds for action, and how findings update experience artifacts, -requirements, design, tests, or strategy. --> +<!-- LLM: Explain how production evidence reaches product and design work. Name the review cadence, participants, thresholds for action, and how findings update experience artifacts, requirements, design, tests, or strategy. --> _How does observation become the next discovery input rather than a dashboard nobody reads?_ diff --git a/templates/engineering/PUBLISHING.md b/templates/engineering/PUBLISHING.md index 87ab4c9..49e7a93 100644 --- a/templates/engineering/PUBLISHING.md +++ b/templates/engineering/PUBLISHING.md @@ -1,9 +1,4 @@ -<!-- LLM: This document defines continuous delivery: how a change that passes TESTING.md -becomes a versioned artifact and safely reaches users. Cover software, packages, APIs, -infrastructure, and documentation that this project actually publishes. Link to official -platform documentation rather than copying volatile provider instructions. Interview the -user about the real release path, promotion gates, rollback, and ownership. Remove LLM -comments as you complete each section. --> +<!-- LLM: This document defines continuous delivery: how a change that passes TESTING.md becomes a versioned artifact and safely reaches users. Cover software, packages, APIs, infrastructure, and documentation that this project actually publishes. Link to official platform documentation rather than copying volatile provider instructions. Interview the user about the real release path, promotion gates, rollback, and ownership. Remove LLM comments as you complete each section. --> # Publishing @@ -11,34 +6,23 @@ _How does a verified change become an artifact and reach users safely?_ ## Artifacts and destinations -<!-- LLM: List what the project publishes and where it goes: application, service, -container, package, binary, schema, infrastructure, docs, or another artifact. Remove rows -that do not apply. --> +<!-- LLM: List what the project publishes and where it goes: application, service, container, package, binary, schema, infrastructure, docs, or another artifact. Remove rows that do not apply. --> | Artifact | Destination | Versioned by | Owner | -|---|---|---|---| +| --- | --- | --- | --- | | _Artifact_ | _Registry, environment, store, or host_ | _Tag, digest, release, or commit_ | _Role/team_ | ## Suggested versioning and change history -<!-- LLM: Treat these as optional recommendations, not requirements. First document the -team's existing versioning, commit, and changelog practices. Suggest Semantic Versioning or -Conventional Commits only when they would make compatibility and release intent clearer. Do -not add enforcement, rewrite history, or change release automation without explicit team -agreement. --> +<!-- LLM: Treat these as optional recommendations, not requirements. First document the team's existing versioning, commit, and changelog practices. Suggest Semantic Versioning or Conventional Commits only when they would make compatibility and release intent clearer. Do not add enforcement, rewrite history, or change release automation without explicit team agreement. --> -- Consider **Semantic Versioning** (`MAJOR.MINOR.PATCH`) when an artifact has a public API or - compatibility contract: incompatible changes may justify `MAJOR`, backward-compatible - features `MINOR`, and backward-compatible fixes `PATCH`. -- Consider **Conventional Commits** (`type(scope): description`) when human- and - machine-readable change history would improve reviews, changelogs, or release automation. -- Keep the workflow the team already uses when it serves them better. Document the chosen - convention and any exceptions; these suggestions do not require enforcement. +- Consider **Semantic Versioning** (`MAJOR.MINOR.PATCH`) when an artifact has a public API or compatibility contract: incompatible changes may justify `MAJOR`, backward-compatible features `MINOR`, and backward-compatible fixes `PATCH`. +- Consider **Conventional Commits** (`type(scope): description`) when human- and machine-readable change history would improve reviews, changelogs, or release automation. +- Keep the workflow the team already uses when it serves them better. Document the chosen convention and any exceptions; these suggestions do not require enforcement. ## Build and continuous delivery -<!-- LLM: Add the exact commands and automation that build, sign, package, and publish. -Explain which TESTING.md gates must pass before an artifact can move forward. --> +<!-- LLM: Add the exact commands and automation that build, sign, package, and publish. Explain which TESTING.md gates must pass before an artifact can move forward. --> ```sh _build / publish command_ @@ -46,25 +30,21 @@ _build / publish command_ ## Environments and promotion -<!-- LLM: Describe the actual path to users (for example preview -> staging -> production), -who or what approves each transition, and whether releases are gradual. Do not invent an -environment that does not exist. --> +<!-- LLM: Describe the actual path to users (for example preview -> staging -> production), who or what approves each transition, and whether releases are gradual. Do not invent an environment that does not exist. --> | From | To | Required evidence / approval | -|---|---|---| +| --- | --- | --- | | _Environment_ | _Environment_ | _CI gate, human approval, change window, or policy_ | ## Deployment verification -<!-- LLM: Name the smoke tests, health checks, and OBSERVABILITY.md signals that confirm a -release is healthy. Separate "deployed" from "verified." --> +<!-- LLM: Name the smoke tests, health checks, and OBSERVABILITY.md signals that confirm a release is healthy. Separate "deployed" from "verified." --> - _Verification and expected result._ ## Rollback and recovery -<!-- LLM: State the exact rollback trigger, authority, mechanism, and data-migration caveats. -Link to a runbook when recovery is more involved than one command. --> +<!-- LLM: State the exact rollback trigger, authority, mechanism, and data-migration caveats. Link to a runbook when recovery is more involved than one command. --> _How is a harmful release stopped or reversed safely?_ diff --git a/templates/engineering/README.md b/templates/engineering/README.md index 1788102..6aebf78 100644 --- a/templates/engineering/README.md +++ b/templates/engineering/README.md @@ -1,17 +1,13 @@ -<!-- LLM: This folder carries the product and experience contract through the complete -engineering lifecycle. Read ../REQUIREMENTS.md first. Fill the canonical lifecycle docs, -then create focused setup guides, runbooks, API references, or operational docs only when -the project needs them. Keep the index current and remove LLM comments as you go. --> +<!-- LLM: This folder carries the product and experience contract through the complete engineering lifecycle. Read ../REQUIREMENTS.md first. Fill the canonical lifecycle docs, then create focused setup guides, runbooks, API references, or operational docs only when the project needs them. Keep the index current and remove LLM comments as you go. --> # Engineering -Engineering begins with the shared requirements contract and follows it through design, -pre-release evidence, continuous delivery, and production learning. +Engineering begins with the shared requirements contract and follows it through design, pre-release evidence, continuous delivery, and production learning. ## Lifecycle | Document | Responsibility | -|---|---| +| --- | --- | | [`ARCHITECTURE.md`](ARCHITECTURE.md) | How domain boundaries and system components satisfy the requirements. | | [`TESTING.md`](TESTING.md) | How tests and CI prove the system before release. | | [`PUBLISHING.md`](PUBLISHING.md) | How verified artifacts are versioned, promoted, deployed, and rolled back. | @@ -20,12 +16,10 @@ pre-release evidence, continuous delivery, and production learning. ## Supporting documentation -<!-- LLM: Create only the focused documents this project needs. Common examples include -development setup, API/interface references, data contracts, security guides, migration -plans, and operational runbooks. Do not duplicate the canonical lifecycle docs above. --> +<!-- LLM: Create only the focused documents this project needs. Common examples include development setup, API/interface references, data contracts, security guides, migration plans, and operational runbooks. Do not duplicate the canonical lifecycle docs above. --> -| Document | Description | -|---|---| +| Document | Description | +| ------------- | -------------------------------- | | _filename.md_ | _What it covers and who uses it_ | ## Decision records @@ -36,5 +30,4 @@ Create the next Architecture Decision Record with: docslime add adr <short-slug> ``` -Keep the decision log in [`adrs/README.md`](adrs/README.md) synchronized with accepted, -superseded, and deprecated records. +Keep the decision log in [`adrs/README.md`](adrs/README.md) synchronized with accepted, superseded, and deprecated records. diff --git a/templates/engineering/TESTING.md b/templates/engineering/TESTING.md index 510dfaf..2f66bec 100644 --- a/templates/engineering/TESTING.md +++ b/templates/engineering/TESTING.md @@ -1,48 +1,35 @@ -<!-- LLM: This document explains how we prove the system fulfills its product goals, experiences, -and requirements. It closes the BDD loop: evidence in ../experience/ and requirements in -../REQUIREMENTS.md should map to something verified here. Interview the -user about how they actually test (or intend to). Remove LLM comments as you complete each -section. --> +<!-- LLM: This document explains how we prove the system fulfills its product goals, experiences, and requirements. It closes the BDD loop: evidence in ../experience/ and requirements in ../REQUIREMENTS.md should map to something verified here. Interview the user about how they actually test (or intend to). Remove LLM comments as you complete each section. --> # Testing -<!-- LLM: One-paragraph summary of the testing philosophy. Ask: "How do you decide something -is correct and shippable?" Capture the spirit (e.g. "behavior-first, fast feedback"). --> +<!-- LLM: One-paragraph summary of the testing philosophy. Ask: "How do you decide something is correct and shippable?" Capture the spirit (e.g. "behavior-first, fast feedback"). --> _How do we know the system works?_ ## Strategy -<!-- LLM: Describe the layers of testing and what each is responsible for. Ask the user which -layers they use and where the emphasis is. Adjust the rows to reality — don't list layers -they don't have. --> +<!-- LLM: Describe the layers of testing and what each is responsible for. Ask the user which layers they use and where the emphasis is. Adjust the rows to reality — don't list layers they don't have. --> | Layer | What it verifies | Tools | -|---|---|---| +| --- | --- | --- | | Unit | _Smallest units of logic_ | _…_ | | Integration | _Components working together_ | _…_ | | End-to-end / behavior | _User-visible behavior derived from ../experience/_ | _…_ | ## Behavior coverage -<!-- LLM: This is the BDD heart of the doc. Map each key experience / requirement to the -test(s) that prove it. Reuse the Given/When/Then scenarios from ../experience/ and the -requirement IDs from ../REQUIREMENTS.md. Ask the user to confirm each important behavior has a -test (or flag it as a gap). --> +<!-- LLM: This is the BDD heart of the doc. Map each key experience / requirement to the test(s) that prove it. Reuse the Given/When/Then scenarios from ../experience/ and the requirement IDs from ../REQUIREMENTS.md. Ask the user to confirm each important behavior has a test (or flag it as a gap). --> -| Experience / Requirement | Scenario (Given/When/Then) | Test | -|---|---|---| -| _Experience name / FR-1_ | _Given … When … Then …_ | _path/to/test_ | +| Experience / Requirement | Scenario (Given/When/Then) | Test | +| ------------------------ | -------------------------- | -------------- | +| _Experience name / FR-1_ | _Given … When … Then …_ | _path/to/test_ | ## Traceability contract -<!-- LLM: Explain the quality trace this project uses. Keep it concrete: product goal -> -experience -> requirement -> BDD scenario -> test, with architecture/ADR links where a -domain boundary or durable decision matters. Remove or shorten if the project is tiny, but -do not leave behavior untraceable. --> +<!-- LLM: Explain the quality trace this project uses. Keep it concrete: product goal -> experience -> requirement -> BDD scenario -> test, with architecture/ADR links where a domain boundary or durable decision matters. Remove or shorten if the project is tiny, but do not leave behavior untraceable. --> | Link | Evidence | -|---|---| +| --- | --- | | Product goal -> experience | _../PRODUCT.md / ../experience/ evidence_ | | Experience -> requirement | _Requirement IDs from ../REQUIREMENTS.md_ | | Requirement -> BDD scenario | _Given/When/Then scenario_ | @@ -51,17 +38,13 @@ do not leave behavior untraceable. --> ## Evaluation against product goals -<!-- LLM: Beyond pass/fail tests, how do we evaluate that the system fulfills the product goals and -success metrics (from ../PRODUCT.md)? This may include metrics, manual evaluation, user -feedback, or LLM/qualitative evals. Ask the user how they judge product-level success, not -just code correctness. --> +<!-- LLM: Beyond pass/fail tests, how do we evaluate that the system fulfills the product goals and success metrics (from ../PRODUCT.md)? This may include metrics, manual evaluation, user feedback, or LLM/qualitative evals. Ask the user how they judge product-level success, not just code correctness. --> - _Metric / eval — how it's measured and what "good" looks like_ ## Running the tests -<!-- LLM: Give the exact commands to run the suite locally and the expectation (e.g. all green, -coverage threshold). Ask the user for the real commands. --> +<!-- LLM: Give the exact commands to run the suite locally and the expectation (e.g. all green, coverage threshold). Ask the user for the real commands. --> ``` _command to run the tests_ @@ -69,14 +52,12 @@ _command to run the tests_ ## Continuous integration -<!-- LLM: Describe when tests run automatically and what gates merges/releases. Reference the -CI config file. Remove if there is no CI yet, but suggest adding it. --> +<!-- LLM: Describe when tests run automatically and what gates merges/releases. Reference the CI config file. Remove if there is no CI yet, but suggest adding it. --> _What runs in CI, and what must pass before merge/release?_ ## Test data & environments -<!-- LLM: How test data and environments are managed (fixtures, seeds, sandboxes, throwaway -dirs). Remove if not applicable. --> +<!-- LLM: How test data and environments are managed (fixtures, seeds, sandboxes, throwaway dirs). Remove if not applicable. --> _How are test data and environments set up and torn down?_ diff --git a/templates/engineering/adrs/README.md b/templates/engineering/adrs/README.md index 90a6030..0b499ab 100644 --- a/templates/engineering/adrs/README.md +++ b/templates/engineering/adrs/README.md @@ -1,12 +1,8 @@ -<!-- LLM: This file is the index for the Architecture Decision Records. It is NOT itself an -ADR. Keep it as a short explainer plus a table of the decisions recorded so far. When you add -or fill in an ADR, add a row to the log below. Remove LLM comments as you go. --> +<!-- LLM: This file is the index for the Architecture Decision Records. It is NOT itself an ADR. Keep it as a short explainer plus a table of the decisions recorded so far. When you add or fill in an ADR, add a row to the log below. Remove LLM comments as you go. --> # Architecture Decision Records -An **Architecture Decision Record (ADR)** captures one significant decision — the context, -the choice made, and its consequences — so the reasoning lives in the repo alongside the -code. Decisions are immutable once accepted: to change one, add a new ADR that supersedes it. +An **Architecture Decision Record (ADR)** captures one significant decision — the context, the choice made, and its consequences — so the reasoning lives in the repo alongside the code. Decisions are immutable once accepted: to change one, add a new ADR that supersedes it. ## Creating an ADR @@ -14,8 +10,7 @@ code. Decisions are immutable once accepted: to change one, add a new ADR that s docslime add adr <short-slug> ``` -This creates the next-numbered record, e.g. `0001-<short-slug>.md`. Fill it in (the file -carries inline guidance), then add a row to the log below. +This creates the next-numbered record, e.g. `0001-<short-slug>.md`. Fill it in (the file carries inline guidance), then add a row to the log below. ## Status values @@ -28,6 +23,6 @@ carries inline guidance), then add a row to the log below. <!-- LLM: Keep this table in sync with the ADR files in this folder. One row per ADR. --> -| ADR | Title | Status | Date | -|---|---|---|---| +| ADR | Title | Status | Date | +| ------ | ------------- | ---------- | ------------ | | _0001_ | _short title_ | _Proposed_ | _YYYY-MM-DD_ | diff --git a/templates/experience/README.md b/templates/experience/README.md index 593128a..d8252dc 100644 --- a/templates/experience/README.md +++ b/templates/experience/README.md @@ -1,20 +1,10 @@ -<!-- LLM: This folder is the continuous-discovery and experience-design workspace. Read -../PRODUCT.md and ../DESIGN.md first when they are retained and applicable. Interview the user about actual evidence; never invent -research, users, quotes, or validation. Keep this README as the operating model and index, -then create one focused file per meaningful opportunity, journey, study, or product slice. -Translate validated findings into stable requirements in ../REQUIREMENTS.md rather than -turning discovery notes into an untraceable backlog. Remove LLM comments as you go. --> +<!-- LLM: This folder is the continuous-discovery and experience-design workspace. Read ../PRODUCT.md and ../DESIGN.md first when they are retained and applicable. Interview the user about actual evidence; never invent research, users, quotes, or validation. Keep this README as the operating model and index, then create one focused file per meaningful opportunity, journey, study, or product slice. Translate validated findings into stable requirements in ../REQUIREMENTS.md rather than turning discovery notes into an untraceable backlog. Remove LLM comments as you go. --> # Experience -This folder connects continuous discovery and experience design to delivery. It captures -what the team has learned from users, the outcomes they need, the opportunities worth -pursuing, and the behavior that would demonstrate improvement. +This folder connects continuous discovery and experience design to delivery. It captures what the team has learned from users, the outcomes they need, the opportunities worth pursuing, and the behavior that would demonstrate improvement. -For a service, library, SDK, CLI, or API, the users may be developers, operators, -integrators, coding agents, or other automated consumers. Keep experience artifacts for -developer experience and agent experience even when product strategy or visual design is -owned elsewhere and omitted from this repo. +For a service, library, SDK, CLI, or API, the users may be developers, operators, integrators, coding agents, or other automated consumers. Keep experience artifacts for developer experience and agent experience even when product strategy or visual design is owned elsewhere and omitted from this repo. ## Discovery practice @@ -29,38 +19,43 @@ _How does the team learn from users and decide what is worth building?_ ## Experience principles -<!-- LLM: Capture the cross-cutting qualities that should be true of every journey. Link to -the corresponding design principle in ../DESIGN.md when one exists. --> +<!-- LLM: Capture the cross-cutting qualities that should be true of every journey. Link to the corresponding design principle in ../DESIGN.md when one exists. --> - _Principle — what it means for a user._ ## Artifact template -<!-- LLM: Use this shape when creating a new opportunity, journey, study, or product-slice -file. Adapt it to the evidence available; do not create empty sections just to satisfy the -template. Requirements should state what must be true, not prescribe architecture. --> +<!-- LLM: Use this shape when creating a new opportunity, journey, study, or product-slice file. Adapt it to the evidence available; do not create empty sections just to satisfy the template. Requirements should state what must be true, not prescribe architecture. --> ```markdown # Opportunity or experience ## Observed need and evidence + ## Desired user and business outcome + ## Users and context + ## Current journey + ## Opportunity and hypothesis + ## Intended behavior + ## Given / When / Then scenarios + ## Constraints and domain language + ## Success signals and telemetry + ## Open questions + ## Related requirements, tests, architecture, and ADRs ``` ## Traceability -Discovery artifacts should link forward to requirements they justify. Requirements should -link back here, tests should prove their acceptance behavior, and observability should show -whether the intended outcome happens in production. +Discovery artifacts should link forward to requirements they justify. Requirements should link back here, tests should prove their acceptance behavior, and observability should show whether the intended outcome happens in production. ```mermaid flowchart LR @@ -75,9 +70,8 @@ flowchart LR ## Index -<!-- LLM: List only artifacts that actually exist. Use one file per substantial artifact -and give each a stable, descriptive lowercase-kebab-case filename. --> +<!-- LLM: List only artifacts that actually exist. Use one file per substantial artifact and give each a stable, descriptive lowercase-kebab-case filename. --> | Document | Kind | Status | What it informs | -|---|---|---|---| +| --- | --- | --- | --- | | _filename.md_ | _Opportunity / journey / study / product slice_ | _Active / validated / retired_ | _Requirement, decision, or open question_ | diff --git a/templates/strategy/README.md b/templates/strategy/README.md index a2ca49a..17fc3db 100644 --- a/templates/strategy/README.md +++ b/templates/strategy/README.md @@ -1,18 +1,12 @@ -<!-- LLM: This folder holds strategic context that is too deep or changeable for PRODUCT.md: -market analysis, competitive landscape, positioning, pricing, business model, roadmap, and -strategic bets. Requirements belong in ../REQUIREMENTS.md, not here. Interview the user about -which strategy artifacts exist or are needed; create one focused file per topic rather than -one giant file. Update the index below as files are added. Remove LLM comments as you go. --> +<!-- LLM: This folder holds strategic context that is too deep or changeable for PRODUCT.md: market analysis, competitive landscape, positioning, pricing, business model, roadmap, and strategic bets. Requirements belong in ../REQUIREMENTS.md, not here. Interview the user about which strategy artifacts exist or are needed; create one focused file per topic rather than one giant file. Update the index below as files are added. Remove LLM comments as you go. --> # Strategy -This folder expands on [`../PRODUCT.md`](../PRODUCT.md) with market, positioning, business, -roadmap, and strategic-bet detail that does not belong in compact product context. +This folder expands on [`../PRODUCT.md`](../PRODUCT.md) with market, positioning, business, roadmap, and strategic-bet detail that does not belong in compact product context. ## What lives here -<!-- LLM: Suggest to the user the documents that commonly live here and create the ones that -fit this project. Keep each in its own file. --> +<!-- LLM: Suggest to the user the documents that commonly live here and create the ones that fit this project. Keep each in its own file. --> - **Market & users** — _market context, segments, demand._ - **Competitive landscape** — _alternatives and how this differs._ @@ -22,9 +16,8 @@ fit this project. Keep each in its own file. --> ## Index -<!-- LLM: Keep a list of the documents actually in this folder, with a one-line description -each. Update it whenever a file is added. --> +<!-- LLM: Keep a list of the documents actually in this folder, with a one-line description each. Update it whenever a file is added. --> -| Document | Description | -|---|---| +| Document | Description | +| ------------- | ---------------- | | _filename.md_ | _what it covers_ |