Documentation Guidelines

Documentation Guidelines

Overview

Produce documentation that is easy to locate, owned by the correct repo/module/feature, and safe to use as a source of truth. Use this skill for monorepos and single-project repos when creating, reorganizing, or updating architecture docs, module docs, feature docs, API contracts, workflows, runbooks, testing notes, or debugging guidance. Prefer searchable filenames with explicit suffixes over repeated README.md files for detailed module docs.

Apply the workflow directly unless the repository has newer explicit agent instructions or a newer docs index that conflicts.

For detailed templates, read references/documentation-guidelines.md.

Non-Negotiable Reading Rule

Before summarizing, moving, deleting, or editing documentation:

1. Read the complete target file, not just search hits. 2. If root docs/README.md exists, read it first. It is the project routing index. 3. Read the owning repo README.md, local agent guide, and repo docs/README.md when they exist. 4. Read repo-level modules.md and features.md when resolving a module or feature. 5. Read the owning module doc at docs/modules/<module-id>/<module-id>-module.md when it exists. If a project still uses legacy docs/modules/<module-id>/README.md, read it and consider migrating it when editing. 6. Read all relationship docs marked Required. 7. Do not infer business logic from filenames, folder names, translated labels, role display names, or stale references. 8. If two docs appear duplicated, read both completely and identify the source-of-truth owner before deleting or merging.

Project Shape

Monorepo

A repo is a monorepo when it has multiple independent apps/services/packages or deployable runtimes, such as apps/*, services/*, or packages/*.

Use this documentation shape:

docs/
  README.md
  naming-and-structure.md
  relationship-map.md
  runbooks/
  decisions/

apps/<repo>/
  README.md
  docs/
    README.md
    modules.md
    features.md
    architecture/
    modules/
      order/
        order-module.md
        features/
          approve-order-api-feature.md
        workflows/
          order-approval-workflow.md
        runbooks/
          debug-order-approval-runbook.md
        order-testing.md
    reference/
    runbooks/
    memories/
    archives/

Root docs/ is a routing and coordination area. Detailed monorepo docs always live inside the owning repository, such as apps/api/docs/..., not under root docs/<repo-id>/....

Root docs/README.md must link to each repo docs index, repo-level modules.md, and repo-level features.md. It must not copy every feature into a full global feature list.

Single Project

A single-project repo may keep all docs under root docs/, but still uses the same index model:

docs/
  README.md
  naming-and-structure.md
  modules.md
  features.md
  architecture/
  modules/
    order/
      order-module.md
      features/
        approve-order-api-feature.md
      workflows/
        order-approval-workflow.md
      runbooks/
        debug-order-approval-runbook.md
      order-testing.md
  reference/
  runbooks/
  memories/
  archives/

Use one repo prompt name for routing, such as Main Repo, API Repo, or a domain-specific project name.

Routing Index Requirements

Root docs/README.md is the first file an AI agent should use to resolve natural-language prompts. It must include:

• Project shape: monorepo or single-project.
• Repo prompt names and repo IDs.
• Links to each repo docs index, modules.md, and features.md.
• A root Module Locator for quick module resolution.
• Cross-repo Relationship Map.
• Independent/tooling areas.
• AI reading workflow and update rules.

Repo-level modules.md lists modules owned by that repo. Repo-level features.md lists features owned by that repo. Detailed module docs should use searchable suffix filenames such as docs/modules/<module-id>/<module-id>-module.md, not repeated module README.md files, unless a project explicitly requires folder landing pages.

File Naming Rules

Use explicit suffixes for detailed docs so developers can find files quickly by name:

Reserve README.md for root/repo entrypoints and intentional index folders. Do not create docs/modules/<module-id>/README.md for new module docs when the project follows suffix naming.

Global Uniqueness Rules

These identifiers must be unique across the whole project:

When the same business concept appears in multiple repos, include owner or surface in the canonical name, such as Approve Order API and Approve Order Office UI.

Aliases are allowed only when each alias maps to exactly one canonical repo, module, or feature. Remove or narrow ambiguous aliases.

Relationship Levels

Use only these values in relationship maps:

Independent/tooling repos must be marked None when they have no product runtime or contract dependency.

Ownership Rules

Place documentation by enforcement owner:

Consumer docs may summarize how they consume a contract, but must link to the owner doc instead of copying the full business rule.

Workflow

When creating or updating docs:

1. Read root docs/README.md when present. 2. Resolve the repo prompt name, module name, and feature name from the user prompt. 3. If only a feature is named, use repo-level feature indexes linked from root docs/README.md to find its owner. 4. Read the owning repo docs index, repo modules.md, repo features.md, owning module *-module.md, and existing feature docs. 5. Read relationship docs marked Required; read Recommended docs for design, contract, workflow, and user-facing changes. 6. Decide whether the work is an index update, module doc, feature doc, API contract, workflow, runbook, memory/convention, archive/move, or cross-repo relationship update. 7. Create or update docs in the owning docs folder. Remove obsolete content instead of appending contradictory sections. 8. Update root and repo indexes when adding, renaming, moving, or archiving repos/modules/features. 9. Search for stale paths, old names, old IDs, and removed terms. 10. Verify links resolve relative to the file location.

If routing remains ambiguous after reading indexes, ask one targeted question instead of guessing.

Frontmatter

Every new or materially rewritten Markdown doc must start with YAML frontmatter:

---
name: Human Readable Title
description: One sentence describing scope and owner.
version: 1.0.0
last_updated: YYYY-MM-DD
maintained_by: Team Or Owner
---

Module docs must also include routing fields:

repo_prompt_name: API Repo
repo_id: api
module_name: Order Module
module_id: order
module_aliases:
  - Orders
related_docs:
  - ../../features.md

Feature docs must also include feature routing fields:

repo_prompt_name: API Repo
repo_id: api
module_name: Order Module
module_id: order
feature_name: Approve Order API
feature_id: approve-order-api
feature_aliases:
  - Order Approval API
related_docs:
  - ../order-module.md
  - ../../../features.md

Preserve existing version/history when migrating docs. Update last_updated and version when content changes materially.

Required Content

For backend/API contract docs, include when applicable:

• Purpose, scope, consumers, and ownership boundary.
• Controllers/routes, requests, resources, models, services, jobs, providers, constants, and config.
• Endpoint table, headers, payload examples, response examples, and error dictionary.
• Permissions, token abilities, feature flags, rate limits, audit rules, and client consumption rules.
• Data model, state transitions, events, queues, cache behavior, side effects, and external dependencies.
• Local development, seed data, migrations, verification commands, troubleshooting hints, and test commands.

For client/workflow docs, include when applicable:

• Entry points, routes, screens, and workflow ownership.
• API or realtime contracts consumed, linked to owner docs.
• Local state/storage behavior and client-only constraints.
• UX/rendering rules without duplicating backend business rules.
• Compatibility, rollout, verification commands, and debugging notes.

Style Rules

• Use frontmatter plus Markdown consistently.
• Use tables for repo names, module indexes, feature indexes, relationships, endpoints, business rules, route maps, error dictionaries, testing matrices, and debugging symptom maps.
• Use Mermaid for actor flows, system flows, state machines, and ERDs when helpful.
• Keep Mermaid labels short. Wrap labels with punctuation in quotes.
• Keep docs concise but complete enough for a future engineer to avoid guessing.
• Delete obsolete text and stale references.
• Link to source-of-truth docs instead of duplicating rules across consumers.

Verification

Before finishing:

• Confirm new or moved docs are discoverable from root docs/README.md and the owning repo indexes.
• Confirm detailed docs use the project's required suffix naming, such as *-module.md, *-feature.md, *-workflow.md, *-runbook.md, *-reference.md, *-testing.md, and *-roadmap.md.
• Confirm root docs do not contain detailed app/service contracts in a monorepo.
• Confirm repo/module/feature names and IDs are unique.
• Confirm independent/tooling areas have None relationship scope when appropriate.
• Confirm new docs have required frontmatter.
• Confirm links resolve relative to the file location.
• Search for stale paths, renamed files, old prompt names, old module names, and old feature names.

Resources

• references/documentation-guidelines.md: Detailed templates for root indexes, repo-level module/feature indexes, module docs, feature docs, API contracts, client workflows, testing, debugging, and cross-repo relationship maps.

Documentation Guidelines Reference

Use this reference when creating or reorganizing documentation for a monorepo or single-project repository. The goal is to make documentation prompt-addressable: when a user names a repo, module, or feature, an AI agent can route to the correct source-of-truth docs without guessing.

Core Model

Root docs/README.md is the project documentation router. It maps natural-language prompt names to repo paths, module indexes, feature indexes, cross-repo relationships, and independent areas.

Detailed docs live with the owner:

• In monorepos, detailed docs always live inside the owning repo, such as apps/api/docs/... or services/worker/docs/....
• In single-project repos, detailed docs live under root docs/....
• Root docs link, summarize, and coordinate. They do not duplicate implementation details owned by child repos.

Recommended Folder Shapes

Monorepo

docs/
  README.md
  naming-and-structure.md
  relationship-map.md
  runbooks/
    README.md
  decisions/
    README.md

apps/api/
  README.md
  docs/
    README.md
    modules.md
    features.md
    architecture/
      README.md
    runbooks/
      README.md
    modules/
      order/
        order-module.md
        features/
          approve-order-api-feature.md
        workflows/
          order-approval-workflow.md
        runbooks/
          debug-order-approval-runbook.md
        order-testing.md
    reference/
      api-errors-reference.md

apps/office-web/
  README.md
  docs/
    README.md
    modules.md
    features.md
    architecture/
      README.md
    runbooks/
      README.md
    modules/
      order-management/
        order-management-module.md
        features/
          approve-order-office-ui-feature.md
        workflows/
          order-approval-screen-workflow.md
        order-management-testing.md

Single Project

docs/
  README.md
  naming-and-structure.md
  modules.md
  features.md
  architecture/
    README.md
  modules/
    order/
      order-module.md
      features/
        approve-order-api-feature.md
      workflows/
        order-approval-workflow.md
      runbooks/
        debug-order-approval-runbook.md
      order-testing.md
  reference/
    api-errors-reference.md
  runbooks/
    README.md

File Naming Rules

Use explicit suffixes for detailed docs so developers can find files quickly by name and do not need to open many repeated README.md files.

Reserve README.md for root/repo entrypoints and intentional folder indexes such as docs/README.md, repo docs/README.md, architecture/README.md, and runbooks/README.md. Do not create docs/modules/<module-id>/README.md for new module docs when the project follows suffix naming.

Root docs/README.md Template

````markdown --- name: Project Documentation Index description: Root documentation index for resolving repos, modules, features, ownership, and cross-repo relationships. version: 1.0.0 last_updated: YYYY-MM-DD maintained_by: Engineering Team project_shape: monorepo ---

Project Documentation Index

How AI Agents Should Read This Project

1. Match the user's prompt against the Repo Prompt Names table. 2. Match the requested module against the Module Locator or repo-level module indexes. 3. Match the requested feature against the repo-level feature indexes linked from this file. 4. Read the owning repo docs index. 5. Read the owning module docs. 6. Read related docs marked as Required in the Relationship Map. 7. Skip unrelated independent/tooling areas unless the prompt explicitly names them.

Repo Prompt Names

Repo Documentation Indexes

Module Locator

Feature Indexes

Root docs link to repo-level feature indexes instead of listing every feature.

Cross-Repo Relationship Map

Independent Areas

Update Rules

• Add every new repo prompt name before using it in docs or prompts.
• Add every new module to the root Module Locator and the owning repo modules.md.
• Add every user-facing, API-facing, or workflow-critical feature to the owning repo features.md.
• Keep canonical module names, module IDs, canonical feature names, and feature IDs unique across the whole project.
• Update the Relationship Map when a feature consumes another repo's API, event, queue, storage, config, or shared package contract.
• Mark independent areas explicitly instead of leaving relationships blank.

````

Repo-Level modules.md Template

````markdown --- name: API Repo Module Index description: Module index for API Repo. version: 1.0.0 last_updated: YYYY-MM-DD maintained_by: Backend Team repo_prompt_name: API Repo repo_id: api ---

API Repo Module Index

````

Repo-Level features.md Template

````markdown --- name: API Repo Feature Index description: Feature index for API Repo. version: 1.0.0 last_updated: YYYY-MM-DD maintained_by: Backend Team repo_prompt_name: API Repo repo_id: api ---

API Repo Feature Index

````

Module Doc Template

Place module docs at docs/modules/<module-id>/<module-id>-module.md inside the owning repo. Reserve README.md for root/repo entrypoints and intentional index folders.

````markdown --- name: Order Module description: Backend order domain, API contracts, state transitions, jobs, and audit behavior. version: 1.0.0 last_updated: YYYY-MM-DD maintained_by: Backend Team repo_prompt_name: API Repo repo_id: api module_name: Order Module module_id: order module_aliases:

• Orders

related_docs:

• ../../features.md
• ../../../../office-web/docs/modules/order-management/order-management-module.md

---

Order Module

Purpose

Describe what this module owns and why it exists.

Ownership Boundary

Prompt Names

Source Paths

Public Contracts

Data Model

Use tables and Mermaid ERDs when they clarify relationships.

Feature Index

Cross-Repo Relationships

Local Development

Document setup commands, seeders, migrations, environment assumptions, and data scenarios.

Testing

Document focused unit, integration, contract, and E2E commands.

Debugging

Document logs, tracing keys, common symptoms, and reproduction steps.

Known Constraints

Document edge cases, historical decisions, migration risks, and compatibility limits. ````

Feature Doc Template

Place feature docs at docs/modules/<module-id>/features/<feature-id>-feature.md inside the owning repo.

````markdown --- name: Approve Order API description: API contract and backend business rules for approving pending orders. version: 1.0.0 last_updated: YYYY-MM-DD maintained_by: Backend Team repo_prompt_name: API Repo repo_id: api module_name: Order Module module_id: order feature_name: Approve Order API feature_id: approve-order-api feature_aliases:

• Order Approval API

related_docs:

• ../order-module.md
• ../../../features.md
• ../../../../../office-web/docs/modules/order-management/features/approve-order-office-ui-feature.md

---

Approve Order API

Summary

Describe the feature and the business outcome in one paragraph.

Owner

Status

Planned, active, deprecated, or archived.

Scope

Actor Flow

flowchart TD
  User["Office user"] --> Submit["Submit approval"]
  Submit --> API["Approve order API"]
  API --> Result["Order approved or rejected"]

System Flow

Document services, events, jobs, side effects, transactions, retries, and cache invalidation.

Contracts

Payloads And Responses

Provide canonical JSON examples for request, success response, validation failure, authorization failure, and business-rule failure.

Data Rules

Cross-Repo Impact

Testing Plan

Debugging Notes

Rollout And Migration

Document feature flags, migrations, backfills, compatibility, and rollback concerns.

Change History

````

Backend/API Contract Checklist

Backend/API feature docs should include:

• Purpose, scope, consumers, and ownership boundary.
• Controllers, routes, requests, resources, models, services, jobs, providers, constants, and config.
• Endpoint table with method, path, guard/scope, request, response, errors, and notes.
• Required headers, payload examples, response examples, and error dictionary.
• Permissions, token abilities, feature flags, rate limits, audit rules, and client consumption rules.
• Data model, state transitions, events, queues, cache behavior, side effects, and external dependencies.
• Local development, seed data, migrations, verification commands, troubleshooting hints, and test commands.

Client/Workflow Checklist

Client/workflow docs should include:

• Entry points, routes, screens, and workflow ownership.
• API or realtime contracts consumed, linked to owner docs.
• Local state/storage behavior and client-only constraints.
• UX and rendering rules without duplicating backend business rules.
• Compatibility notes, rollout notes, verification commands, and debugging notes.

Client docs should use a consumption table instead of copying backend rules:

Relationship Levels

Use Optional only for background context. If a related doc can change contract behavior, rollout, tests, or user-facing behavior, use Recommended or Required.

AI Prompt Resolution Workflow

When a user asks for design, implementation, debugging, or testing work:

1. Read root docs/README.md. 2. Resolve repo prompt name from the user prompt. 3. Resolve module name or feature name. Canonical names and IDs are project-wide unique, so a named feature should identify one owner doc. 4. If the prompt names both repo and module, trust that routing unless docs show ambiguity. 5. Read the owning repo docs index. 6. If the prompt only names a feature, use repo-level feature indexes linked from root docs/README.md to find its owner doc. 7. Read the owning module *-module.md. 8. Read existing feature docs if the feature already exists. 9. Read relationship docs marked Required. 10. For design work, also read testing/debug/runbook docs if listed by the module. 11. If the prompt is ambiguous after reading indexes, ask one targeted question instead of guessing.

Example prompt:

I want to build order approval in API Repo, Order Module. Analyze and design the feature.

Expected reading path:

Update Checklist

When adding a new repo, module, feature, or cross-repo behavior:

1. Update root docs/README.md. 2. Update the owning repo docs/README.md. 3. Update the owning repo modules.md or features.md. 4. Update or create the owning module *-module.md. 5. Create or update feature docs. 6. Confirm canonical module and feature names/IDs are unique across the project. 7. Add cross-repo relationships if contracts, workflows, events, jobs, shared packages, or data dependencies cross repo boundaries. 8. Mark independent areas as None when they do not coordinate with product runtime behavior. 9. Add testing and debugging notes close to the owning module/feature docs. 10. Search for stale old paths, old prompt names, old module names, and old feature names. 11. Verify every linked file exists. 12. Confirm detailed docs use explicit suffix filenames: *-module.md, *-feature.md, *-workflow.md, *-runbook.md, *-reference.md, *-testing.md, or *-roadmap.md.

Markdown Style

• Use frontmatter plus Markdown consistently.
• Use tables for repo names, module indexes, feature indexes, relationships, endpoints, business rules, route maps, error dictionaries, testing matrices, and debugging symptom maps.
• Use Mermaid for actor flows, system flows, state machines, and ERDs when helpful.
• Keep Mermaid labels short. Wrap labels with punctuation in quotes.
• Keep docs concise but complete enough for a future engineer to avoid guessing.
• Delete obsolete text and stale references.
• Link to source-of-truth docs instead of duplicating rules across consumers.