jd-docs

What this skill does

# Johnny.Decimal Documentation

Scaffold, validate, and maintain [Johnny.Decimal](https://johnnydecimal.com/) documentation structure with sensible defaults and per-project customization.

## Quick Start

```bash
# Scaffold a new structure
uv run scripts/jd_init.py --dry-run   # Preview first
uv run scripts/jd_init.py             # Create docs/ with defaults
uv run scripts/jd_init.py --diataxis  # Include Diataxis areas (41-44)

# Validate existing structure
uv run scripts/jd_validate.py --dir docs

# Regenerate README index
uv run scripts/jd_index.py --dir docs

# Day-2: Add a new area
uv run scripts/jd_add_area.py --prefix 40 --name operations --dry-run

# Day-2: Classify unorganized files
uv run scripts/jd_classify.py docs/*.md
uv run scripts/jd_classify.py docs/*.md --diataxis  # With quadrant info

# Day-2: Move a file to an area
uv run scripts/jd_add.py docs/roadmap.md 00 --dry-run
```

See [WORKFLOW.md](WORKFLOW.md) for the full methodology.

## Capabilities

- **Scaffolding** (`jd_init.py`) — Create J.D directory tree with README templates; supports `--product` for monorepo sub-trees, `--init-config` to generate `.jd-config.json`, and `--diataxis` to include Diataxis quadrant areas (41-44)
- **Validation** (`jd_validate.py`) — Check `NN-kebab-case` naming, detect orphan files, verify README presence per area; `--strict` for CI enforcement
- **Index generation** (`jd_index.py`) — Generate/update root README with table or tree index; preserves custom content via `<!-- JD:INDEX:START/END -->` markers
- **Migration** (Claude-driven) — Classify flat docs into J.D areas using naming heuristics, present a move plan, execute interactively

## Day-2 Operations

- **Add area** (`jd_add_area.py`) — Create a new J.D area with prefix, name, README stub, config update, and auto re-index
- **Classify** (`jd_classify.py`) — Classify files into areas using keyword heuristics with confidence scoring (high/medium/low); `--diataxis` adds Diataxis quadrant column, `--diataxis-move` routes files to quadrant areas (41-44)
- **Add/move file** (`jd_add.py`) — Move a file to an area with auto-normalized kebab-case naming and cross-reference detection

## Default Area Scheme

| Prefix | Name | Purpose |
|--------|------|---------|
| `00-` | getting-started | Onboarding, setup, quick start, MVP |
| `10-` | product | Specs, features, roadmap, design, branding |
| `20-` | architecture | Tech decisions, system design, integration |
| `30-` | research | Spikes, investigations, reference material |
| `90-` | archive | Historical/deprecated docs |

Gap at 40-80 reserved for per-project customization (e.g., `40-operations`).

**With `--diataxis`**, areas 41-44 are added for Diataxis quadrants:

| `41-` | tutorials | Tutorials — step-by-step lessons (Diataxis) |
| `42-` | how-to | How-to guides — practical tasks (Diataxis) |
| `43-` | reference | Reference — technical descriptions (Diataxis) |
| `44-` | explanation | Explanation — conceptual discussions (Diataxis) |

## Config File (.jd-config.json)

Optional per-project override at project root:

```json
{
  "version": 1,
  "root": "docs",
  "areas": { "00": "getting-started", "10": "product", "20": "architecture", "30": "research", "90": "archive" },
  "products": [],
  "ignore": ["adr", "*.pdf"],
  "readme_format": "table"
}
```

Create with `uv run scripts/jd_init.py --init-config`. All fields have sensible defaults.

## Common Issues

| Issue | Fix |
|-------|-----|
| `uv` not found | `curl -LsSf https://astral.sh/uv/install.sh \| sh` or run with `python3 scripts/jd_init.py` |
| Orphan files in validation | Move to area dir, or add to `"ignore"` in `.jd-config.json` |
| Index appended at wrong position | Move `<!-- JD:INDEX:START/END -->` markers to desired location after first run |
| Low confidence on all files | Expand keywords in config or use Claude-driven classification |

See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for all error scenarios.

## References

- [WORKFLOW.md](WORKFLOW.md) — Full methodology (discovery, config, scaffold, validate, index, migrate, day-2)
- [EXAMPLES.md](EXAMPLES.md) — Real-world examples for all operations
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — Error handling and debugging tips