# Docs Conventions

> Shared documentation conventions — templates, diagram type selection, staleness detection, severity classification. Use when agents need doc generation or audit context.

- Skill: `kinginyellows/docs-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kinginyellows/docs-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinginyellows/docs-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: kinginyellows (https://skillmd.com/u/kinginyellows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kinginyellows/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

| Level | Meaning | Examples |
|-------|---------|---------|
| P1 | Missing critical docs | No README, undocumented public API, no architecture overview |
| P2 | Stale docs | Code changed but docs not updated, broken references |
| P3 | Structural improvements | Missing sections, no cross-links, inconsistent formatting |

## Health Score Formula

```text
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

```markdown
# {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

```markdown
# {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

```markdown
# 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

````markdown
# 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:

| Scenario | Diagram Type | Mermaid Syntax |
|----------|-------------|----------------|
| Module dependencies / imports | Flowchart | `flowchart LR` |
| API call sequences / message exchange | Sequence | `sequenceDiagram` |
| Class / type hierarchies | Class | `classDiagram` |
| State machines / workflows | State | `stateDiagram-v2` |
| Database schemas / entity relationships | ER | `erDiagram` |
| System architecture (high-level) | Flowchart | `flowchart TB` + subgraphs |
| Directory / file layout | Mindmap | `mindmap` |
| Data flow / pipelines | Flowchart | `flowchart LR` |
| Git branching strategies | Gitgraph | `gitgraph` (if supported) |

### 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):

| Signal | Project Type | Doc Strategy |
|--------|-------------|-------------|
| `.claude-plugin/plugin.json` | Claude Code plugin | CLAUDE.md, command/agent docs |
| `Cargo.toml` | Rust | README, crate docs, `#[deny(missing_docs)]` |
| `pyproject.toml` / `setup.py` | Python | README, docstring coverage |
| `go.mod` | Go | README, godoc conventions |
| `package.json` + `tsconfig.json` | TypeScript | README, TSDoc/JSDoc coverage |
| `package.json` (no tsconfig) | JavaScript | README, JSDoc coverage |

### 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:

```json
{
  "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:

```html
<!-- 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:

```bash
# 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