PromptProduct Management
Review requirements for implementation gaps
Find missing states, unclear acceptance criteria, and contradictory requirements in a supplied brief.
✳Claude
By Dave AIDave AI original
MIT · FreeView prompt
Installable skillApache-2.0
Technical Documentation
Technical documentation standards — document structure, writing style, file organisation, mermaid diagrams, and validation. Referenced by do-docs and tech-docs-writer.
instructions.md
--- name: do-tech-docs description: Technical documentation standards — document structure, writing style, file organisation, mermaid diagrams, and validation. Referenced by do-docs and tech-docs-writer. user-invocable: false disable-model-invocation: true --- # Technical Documentation Produce technical documentation that explains **what** systems do, **how** they interact, and **why** specific choices were made. **Primary audience: LLMs.** These docs will be loaded into LLM context windows during development tasks. Every token must earn its place. Write for machine comprehension first — dense, precise, and structurally consistent. Avoid prose padding, narrative flow, and filler sentences that a human might appreciate but an LLM gains nothing from. Avoid documenting business processes or product capabilities. ## Repository Type Detection A project is a **mono-repo** if any of the following are present: - `package.json` with a `workspaces` field - `pnpm-workspace.yaml` - `lerna.json` - `Cargo.toml` with a `[workspace]` section - `go.work` file - Multiple `pyproject.toml` files in subdirectories - `nx.json` - `rush.json` If none of these indicators are found, treat the project as a **single-repo**. This determination controls where documentation is stored — see [File Organisation](#file-organisation). ## Documentation Principles ### Include - **Purpose and function**: What each component does and why it exists - **Technology choices**: What is used and why it was selected - **Integration points**: How components communicate and depend on each other - **Data flow**: How data moves through the system - **Architectural patterns**: Design patterns employed and their rationale - **Accessibility patterns**: ARIA attribute usage, focus management, keyboard navigation, screen reader support, and WCAG compliance level. Especially important for government or public-sector projects. - **Validation and business rules**: Form validation logic, required field rules, conditional visibility, and domain constraints that the application enforces - **Mermaid diagrams**: Every document describing interactions or flows must include at least one diagram ### Exclude - **Implementation code**: No function bodies, algorithms, or internal logic as code blocks - **Infrastructure configuration**: No CDK, Terraform, Docker Compose, or config file content - **CLI commands**: No terminal commands or deployment scripts (see exception below) - **API endpoint definitions**: No route paths, request/response schemas, or curl examples ### Include as Structured Tables (Not Code Blocks) - **Component/module public API**: Props, parameters, exported types, and return values — documented as tables, not code snippets - **Context/hook API surface**: What a context provider or hook exposes to consumers ### Optional: Developer Onboarding Section When documenting a full project (not a single component), include a brief onboarding section in `architecture-overview.md` or a dedicated `getting-started.md`: - Prerequisites (runtime versions, package manager) - Install and run commands - Key scripts (build, test, lint) Keep to under 20 lines. This is the one context where CLI commands are acceptable. ## Document Structure Every document must start with a YAML frontmatter block. This gives an LLM immediate context about what the document covers without reading the full body. ```markdown --- title: <descriptive title> scope: <component | service | architecture | decision> relates-to: [list of other doc filenames this connects to] last-verified: <YYYY-MM-DD when last checked against source code> --- ## Overview <1-2 sentences: what this covers, stated as facts not narrative.> ## <Core Content> <Main documentation. Use H2/H3 headings as section labels. Prefer bullet points and tables over paragraphs. Each section should be independently useful — an LLM may retrieve a single section, not the whole document.> ## Integration Points <How this component connects to others. Include a Mermaid diagram.> ## Design Decisions <Decision: rationale format. No preamble.> ``` ### Token Budget Docs are loaded into LLM context alongside code, conversation history, and tool results. Context is finite and expensive. - **Target: 200-500 lines per document.** If a document exceeds this, split it. - Use bullet points and tables instead of paragraphs — same information, fewer tokens - State facts directly: "Auth uses JWT with RS256" not "The authentication system has been designed to utilise JSON Web Tokens using the RS256 algorithm" - Define terms inline on first use with parenthetical notation: "The gateway (API entry point handling routing and auth) forwards requests to..." - Omit transition sentences, introductory phrasing, and summaries of what was just said - Prefer structured lists over prose for enumerating components, dependencies, or flows ### File Organisation #### Root-level directory structure (all projects) ``` docs/ technical/ — root-level / cross-cutting technical docs product/ — product documentation (features, user guides, business context) maverick/ — maverick-generated project skills (if applicable) ``` #### Single-repo projects All technical docs go in `docs/technical/` — no additional nesting required. #### Mono-repo projects - Cross-cutting and architectural docs go in `docs/technical/` at the repo root - Package-specific technical docs go in `<package>/docs/` (no `technical/` subdirectory needed since package docs are inherently technical) - Each `<package>/docs/` maintains its own `index.md` listing that package's documents - Product docs are **never** stored at the package level — always in root `docs/product/` #### General rules - Create **separate files** for distinct topics rather than monolithic documents - Use `kebab-case.md` naming (e.g. `authentication-architecture.md`) - Each file should be self-contained but may cross-reference others via `relates-to` in frontmatter - Maintain an `index.md` in `docs/technical/` listing all documents with one-line descriptions — this serves as the entry point for LLM context loading - In mono-repos, root `docs/technical/index.md` should link to each `<package>/docs/index.md` ### Sizing | Task size | Documentation depth | | ----------------------------------- | -------------------------------------------------- | | Trivial (config, minor change) | 2-3 sentences in an existing doc or commit message | | Small (single component) | Overview + core content (under 200 lines) | | Medium (feature, service) | Full document structure (200-500 lines) | | Large (cross-cutting, architecture) | Split into multiple focused documents | ### Within a Document Scale section depth to component complexity. Indicators that a component needs deeper coverage: - File exceeds 300 lines - Contains business/domain logic (rule engines, calculations, transformations) - Has multiple distinct output modes (e.g., screen rendering, PDF export, print view) - Serves as an aggregation point for data from multiple sources For these components, document each distinct responsibility separately rather than summarising the whole. ## Mermaid Diagram Standards Use diagrams to visualise: - **Service interactions**: `sequenceDiagram` or `flowchart` - **Data flows**: `flowchart` or `sequenceDiagram` - **Architecture overviews**: `flowchart` or `C4Context` - **State transitions**: `stateDiagram-v2` Guidelines: - Every diagram must have a descriptive title - Use clear, descriptive node labels — not abbreviations or internal variable names - Keep diagrams focused on one concept; prefer multiple simple diagrams over one complex one - Aim for no more than 15-20 nodes per diagram ## Writing Style - **Dense, not verbose**: State facts. Skip introductions, transitions, and conclusions. An LLM does not need to be "eased into" a topic. - **Precise**: Use exact technology names and versions. "PostgreSQL 16 with row-level security" not "a relational database with access controls". - **Consistent terminology**: Use the same term for the same concept everywhere. Define domain terms inline on first use. - **Structured over narrative**: Prefer `key: value` patterns, bullet lists, and tables. Reserve prose for explaining *why* — rationale that cannot be expressed as a list. ## Validation Checklist Before finalising documentation: - [ ] All factual claims verified against source code - [ ] Mermaid diagrams render correctly (valid syntax) - [ ] No implementation code, config snippets, or CLI commands included (API surface tables are acceptable) - [ ] Cross-references use correct relative paths - [ ] Document is under 500 lines (split if larger) - [ ] YAML frontmatter present with title, scope, relates-to, last-verified - [ ] `docs/technical/index.md` updated if this is a new document (and `<package>/docs/index.md` for mono-repo package docs) - [ ] Bullet points and tables used instead of prose where possible - [ ] All public exports from documented modules are covered (check for multiple exports per file) - [ ] Numbering, terminology, and facts are consistent across all documents in the set <!-- maverick-plugin-version: 5.1.1 -->--- name: do-tech-docs description: Technical documentation standards — document structure, writing style, file organisation, mermaid diagrams, and validation. Referenced by do-docs and tech-docs-writer. user-invocable: false disable-model-invocation: true --- # Technical Documentation Produce technical documentation that explains **what** systems do, **how** they interact, and **why** specific choices were made. **Primary audience: LLMs.** These docs will be loaded into LLM context windows during development tasks. Every token must earn its place. Write for machine comprehension first — dense, precise, and structurally consistent. Avoid prose padding, narrative flow, and filler sentences that a human might appreciate but an LLM gains nothing from. Avoid documenting business processes or product capabilities. ## Repository Type Detection A project is a **mono-repo** if any of the following are present: - `package.json` with a `workspaces` field - `pnpm-workspace.yaml` - `lerna.json` - `Cargo.toml` with a `[workspace]` section - `go.work` file - Multiple `pyproject.toml` files in subdirectories - `nx.json` - `rush.json` If none of these indicators are found, treat the project as a **single-repo**. This determination controls where documentation is stored — see [File Organisation](#file-organisation). ## Documentation Principles ### Include - **Purpose and function**: What each component does and why it exists - **Technology choices**: What is used and why it was selected - **Integration points**: How components communicate and depend on each other - **Data flow**: How data moves through the system - **Architectural patterns**: Design patterns employed and their rationale - **Accessibility patterns**: ARIA attribute usage, focus management, keyboard navigation, screen reader support, and WCAG compliance level. Especially important for government or public-sector projects. - **Validation and business rules**: Form validation logic, required field rules, conditional visibility, and domain constraints that the application enforces - **Mermaid diagrams**: Every document describing interactions or flows must include at least one diagram ### Exclude - **Implementation code**: No function bodies, algorithms, or internal logic as code blocks - **Infrastructure configuration**: No CDK, Terraform, Docker Compose, or config file content - **CLI commands**: No terminal commands or deployment scripts (see exception below) - **API endpoint definitions**: No route paths, request/response schemas, or curl examples ### Include as Structured Tables (Not Code Blocks) - **Component/module public API**: Props, parameters, exported types, and return values — documented as tables, not code snippets - **Context/hook API surface**: What a context provider or hook exposes to consumers ### Optional: Developer Onboarding Section When documenting a full project (not a single component), include a brief onboarding section in `architecture-overview.md` or a dedicated `getting-started.md`: - Prerequisites (runtime versions, package manager) - Install and run commands - Key scripts (build, test, lint) Keep to under 20 lines. This is the one context where CLI commands are acceptable. ## Document Structure Every document must start with a YAML frontmatter block. This gives an LLM immediate context about what the document covers without reading the full body. ```markdown --- title: <descriptive title> scope: <component | service | architecture | decision> relates-to: [list of other doc filenames this connects to] last-verified: <YYYY-MM-DD when last checked against source code> --- ## Overview <1-2 sentences: what this covers, stated as facts not narrative.> ## <Core Content> <Main documentation. Use H2/H3 headings as section labels. Prefer bullet points and tables over paragraphs. Each section should be independently useful — an LLM may retrieve a single section, not the whole document.> ## Integration Points <How this component connects to others. Include a Mermaid diagram.> ## Design Decisions <Decision: rationale format. No preamble.> ``` ### Token Budget Docs are loaded into LLM context alongside code, conversation history, and tool results. Context is finite and expensive. - **Target: 200-500 lines per document.** If a document exceeds this, split it. - Use bullet points and tables instead of paragraphs — same information, fewer tokens - State facts directly: "Auth uses JWT with RS256" not "The authentication system has been designed to utilise JSON Web Tokens using the RS256 algorithm" - Define terms inline on first use with parenthetical notation: "The gateway (API entry point handling routing and auth) forwards requests to..." - Omit transition sentences, introductory phrasing, and summaries of what was just said - Prefer structured lists over prose for enumerating components, dependencies, or flows ### File Organisation #### Root-level directory structure (all projects) ``` docs/ technical/ — root-level / cross-cutting technical docs product/ — product documentation (features, user guides, business context) maverick/ — maverick-generated project skills (if applicable) ``` #### Single-repo projects All technical docs go in `docs/technical/` — no additional nesting required. #### Mono-repo projects - Cross-cutting and architectural docs go in `docs/technical/` at the repo root - Package-specific technical docs go in `<package>/docs/` (no `technical/` subdirectory needed since package docs are inherently technical) - Each `<package>/docs/` maintains its own `index.md` listing that package's documents - Product docs are **never** stored at the package level — always in root `docs/product/` #### General rules - Create **separate files** for distinct topics rather than monolithic documents - Use `kebab-case.md` naming (e.g. `authentication-architecture.md`) - Each file should be self-contained but may cross-reference others via `relates-to` in frontmatter - Maintain an `index.md` in `docs/technical/` listing all documents with one-line descriptions — this serves as the entry point for LLM context loading - In mono-repos, root `docs/technical/index.md` should link to each `<package>/docs/index.md` ### Sizing | Task size | Documentation depth | | ----------------------------------- | -------------------------------------------------- | | Trivial (config, minor change) | 2-3 sentences in an existing doc or commit message | | Small (single component) | Overview + core content (under 200 lines) | | Medium (feature, service) | Full document structure (200-500 lines) | | Large (cross-cutting, architecture) | Split into multiple focused documents | ### Within a Document Scale section depth to component complexity. Indicators that a component needs deeper coverage: - File exceeds 300 lines - Contains business/domain logic (rule engines, calculations, transformations) - Has multiple distinct output modes (e.g., screen rendering, PDF export, print view) - Serves as an aggregation point for data from multiple sources For these components, document each distinct responsibility separately rather than summarising the whole. ## Mermaid Diagram Standards Use diagrams to visualise: - **Service interactions**: `sequenceDiagram` or `flowchart` - **Data flows**: `flowchart` or `sequenceDiagram` - **Architecture overviews**: `flowchart` or `C4Context` - **State transitions**: `stateDiagram-v2` Guidelines: - Every diagram must have a descriptive title - Use clear, descriptive node labels — not abbreviations or internal variable names - Keep diagrams focused on one concept; prefer multiple simple diagrams over one complex one - Aim for no more than 15-20 nodes per diagram ## Writing Style - **Dense, not verbose**: State facts. Skip introductions, transitions, and conclusions. An LLM does not need to be "eased into" a topic. - **Precise**: Use exact technology names and versions. "PostgreSQL 16 with row-level security" not "a relational database with access controls". - **Consistent terminology**: Use the same term for the same concept everywhere. Define domain terms inline on first use. - **Structured over narrative**: Prefer `key: value` patterns, bullet lists, and tables. Reserve prose for explaining *why* — rationale that cannot be expressed as a list. ## Validation Checklist Before finalising documentation: - [ ] All factual claims verified against source code - [ ] Mermaid diagrams render correctly (valid syntax) - [ ] No implementation code, config snippets, or CLI commands included (API surface tables are acceptable) - [ ] Cross-references use correct relative paths - [ ] Document is under 500 lines (split if larger) - [ ] YAML frontmatter present with title, scope, relates-to, last-verified - [ ] `docs/technical/index.md` updated if this is a new document (and `<package>/docs/index.md` for mono-repo package docs) - [ ] Bullet points and tables used instead of prose where possible - [ ] All public exports from documented modules are covered (check for multiple exports per file) - [ ] Numbering, terminology, and facts are consistent across all documents in the set <!-- maverick-plugin-version: 5.1.1 -->
COMPATIBILITY & REFERENCES
Platform guidance
Imported from the listed AgentSkill.sh category. Complete supplied package files and notices are retained. Required external tools and credentials are not installed. No bundled code was executed during import. Individual agent task behavior has not been tested.