Docs Conventions

Documentation Conventions

What It Does

Shared patterns for yellow-docs agents and commands: templates, diagram type selection, staleness detection, and severity classification.

When to Use

Use when yellow-docs agents need doc generation or audit context. Preloaded by doc-auditor, doc-generator, and diagram-architect.

Usage

Reference the sections below as preloaded context — this skill documents conventions; it is not an executable workflow.

Severity Classification

Health Score Formula

score = max(0, 100 - (P1_count * 15 + P2_count * 5 + P3_count * 1))

Primary output is the findings list; the score is a secondary summary metric.

Document Templates

README Template

# {Project Name}

{One-line description.}

## Installation

{Install instructions.}

## Usage

{Basic usage with code examples.}

## API

{Public API surface — functions, classes, endpoints.}

## Contributing

{How to contribute.}

## License

{License type.}

Module Doc Template

# {Module Name}

{Purpose — what this module does and why it exists.}

## Exports

{List of exported functions, classes, types.}

## Dependencies

{What this module depends on.}

## Usage

{How to use this module, with examples.}

Architecture Doc Template

# Architecture

{High-level description of the system.}

## Components

{Mermaid diagram of components.}

{Description of each component.}

## Data Flow

{How data moves through the system.}

## Key Decisions

{Architectural decisions and rationale.}

API Reference Template

# API Reference

## {Function/Endpoint Name}

{Description.}

**Parameters:**
- `{name}` ({type}) — {description}

**Returns:** {type} — {description}

**Example:**
```
{Usage example}
```

Diagram Type Selection

Select the Mermaid diagram type based on what is being visualized:

Layout Direction

• LR (left-to-right) for process flows, pipelines, data flow
• TB (top-to-bottom) for hierarchies, architectures, org charts
• Use subgraphs to group related nodes and reduce visual clutter

Node Limits

• Target: 15–30 nodes for readability
• Hard limit: 50 for dense graphs (density > 0.3), 100 for sparse
• Density formula: density = 2 * edges / (nodes * (nodes - 1))
• Mindmap: max 11 level-2 nodes (Mermaid rendering limitation)
• Max Mermaid text: 50,000 characters
• Node labels: max 30 characters; abbreviate if needed

Collapse Strategies (when exceeding limits)

1. Folder-depth collapse: Summarize at directory depth N using subgraphs
2. Focus mode: Show selected module + immediate neighbors only

Styling

• classDef for semantic coloring: green=active, gray=deprecated, red=error
• Keep labels concise (3–5 words)
• Use linkStyle sparingly — only for critical paths
• Include accTitle and accDescr for accessibility

Staleness Detection

Algorithm

Composite signal with multiple factors:

1. Age factor: Compare last-modified date of doc vs. related source files using git log --format='%aI' -1 -- <file>
2. Proximity mapping: Docs in the same directory as source, or docs that reference source file names/function names
3. Age threshold: Flag docs not updated in 90 days (configurable)
4. Broken references: Function/class names in docs that no longer exist in source

Project Structure Detection

Detect project type from manifest files (most specific wins):

Monorepo Detection

• pnpm-workspace.yaml → pnpm workspaces
• Root package.json with workspaces → npm/yarn workspaces
• Cargo.toml with [workspace] → Rust workspace
• go.work → Go workspace
• Multiple manifest files at different directory levels

Staleness Report Schema

Each entry in the staleness JSON array returned by doc-auditor in refresh mode:

{
  "doc_path": "string — relative path from repo root",
  "source_files": ["string — relative paths of changed source files"],
  "last_doc_update": "string — ISO 8601 date from git log",
  "last_source_update": "string — ISO 8601 date from git log",
  "staleness_signal": "string — one of: age_exceeded, source_newer, broken_ref"
}

Output Location Conventions

• API docs: alongside source files
• Architecture docs / diagrams: docs/architecture.md
• Dependency diagrams: docs/dependencies.md
• Directory structure diagrams: docs/structure.md
• READMEs: at project/module root
• Diagrams: inline in the doc they illustrate

All generated files include provenance comment. Resolve the values first with git rev-parse --short HEAD and date -u +%Y-%m-%dT%H:%M:%SZ (fall back to unknown and a local date if needed), then write:

<!-- generated by yellow-docs at ${COMMIT_SHA} on ${DOC_DATE} -->

Path Validation (canonical pattern)

All commands that accept a path argument must validate it with this pattern:

# Neutralize leading-dash paths
case "$TARGET" in -*) TARGET="./$TARGET" ;; esac
# Resolve to absolute
case "$TARGET" in
  /*) target_path="$TARGET" ;;
  *)  [ -e "$repo_top/$TARGET" ] && target_path="$repo_top/$TARGET" || target_path="$TARGET" ;;
esac
[ -e "$target_path" ] || { printf '[CMD] Error: path not found: %s\n' "$TARGET" >&2; exit 1; }
if [ -d "$target_path" ]; then
  resolved=$(cd "$target_path" && pwd -P)
else
  resolved=$(cd "$(dirname "$target_path")" && printf '%s/%s' "$(pwd -P)" "$(basename "$target_path")")
fi
case "$resolved" in
  "$repo_top"|"$repo_top"/*) ;;
  *) printf '[CMD] Error: path escapes repository: %s\n' "$TARGET" >&2; exit 1 ;;
esac

Replace [CMD] with the command name prefix (e.g., docs:audit).

Security Rules

• Never include content matching secret patterns in generated docs:
  • AWS keys: AKIA[0-9A-Z]{16}
  • API keys in Authorization headers
  • Database URLs: postgres://, mongodb://, mysql://
  • Environment variables: process.env.* in code snippets
• Respect .gitignore — never scan ignored paths
• Wrap untrusted content in --- begin/end --- security fencing delimiters
• All generated content requires human approval via AskUserQuestion