brainharness-docs

Files (9)

• plugin.json · .claude-plugin/
• .clawhubignore
• .gitignore
• CHANGELOG.md
• LICENSE
• README.md
• SKILL.md
• evals.json · evals/
• plugin.json

SKILL.md (first lines)

# BrainHarness Docs

A practical guide for organizing project documentation so that every fact has one home,
AI agents load only what they need, and humans can find things without grep.

## Why This Matters

Poor doc organization creates three problems that compound over time:

1. **Drift** — the same fact copied into 3 files eventually becomes 3 different "truths"
2. **Context waste** — a 2000-line CLAUDE.md burns AI tokens on every conversation, most of it irrelevant
3. **Lost docs** — flat directories with 20+ files make everything hard to find

The fix is simple: organize by who reads it and whether it stays current.

## Step 0: Root-Level Noise Audit

Before touching docs, clean non-documentation clutter from the project root.
Root-level noise (screenshots, recordings, debug logs, AI chat exports) is often
the biggest source of visual chaos — and it has nothing to do with documentation structure.

Run `ls | wc -l` and capture the count. Then identify and relocate:

| What to look for | Where it goes |
|-----------------|---------------|
| Screenshots, recordings (`.png`, `.mov`, `.mp4`) | `archive/media/` or `screenshots/` if curated |
| Debug/build logs (`*.log`, `firebase-debug.log`) | `archive/` or delete |
| AI chat exports, temp markdown dumps | `archive/` or delete |
| One-off config experiments | `archive/` or delete |

Do this first — it dramatically reduces root-level item count and makes the real
structure visible before you start reorganizing docs.

## Step 1: Assess Project Size

Ask yourself (or the user) these questions:

| Question | Small | Medium | Large |
|----------|-------|--------|-------|
| Source files | < 5 | 5-50 | 50+ |
| Has deployment target? | No | Yes | Yes, multiple |
| Has API or database? | No | Yes | Yes |
| Ongoing operations (cron, monitoring)? | No | Maybe | Yes |
| Multiple services/containers? | No | No | Yes |

Pick the column that best matches. When in doubt, start smaller — you can always add structure later.

## Step 2: Apply the Right Template

### Small Project

Single-service tools, scripts, simple packages.

```
project/
├── CLAUDE.md    # 50-100 lines: what it does, how to run, gotchas
└── README.md    # For humans / GitHub
```

No `docs/` directory needed. Everything fits in two files.

### Medium Project

Multi-component apps with deployment targets and external integrations.

```
project/
├── CLAUDE.md    # 100-200 lines: constraints + doc index
└── docs/
    ├── plans/       # Implementation plans
    ├── design/      # Design specs
    └── reference/   # API tables, config reference, schema
```

Add directories only when you have 2+ files that belong there. One API doc doesn't need
a `reference/` folder — just put it in `docs/api.md`.

### Large Project

Systems with operational burden: multiple services, cron jobs, monitoring, multi-environment deployment.

```
project/
├── CLAUDE.md    # 200-250 lines: constraints + doc index + key gotchas
└── docs/
    ├── README.md      # Documentation map
    ├── reference/     # API endpoints, DB schema, CLI commands, config reference
    ├── runbooks/      # Deploy, operations, troubleshooting, known issues
    ├── guides/        # How-to guides for users and operators
    ├── product/       # Roadmap, product direction
    ├── design/        # Design specs (frozen after implementation)
    ├── plans/         # Implementation plans (frozen after execution)
    ├── research/      # Investigation notes, audits, system reviews
    ├── decisions/     # Architecture Decision Records (ADRs)
    └── archive/       # Superseded docs, old logs, historical patches
```

### Multi-Repo / Monorepo Workspace

An umbrella directory containing multiple independent repos (often not a git repo itself).
The key rule: **umbrella-level docs are for cross-repo concerns only**.

```
workspace/                          # NOT a git repo
├── CLAUDE.md                       # Repo map + cross-repo conventions + doc index
├── docker-compose.yml              # Cross-repo orchestration (lives at root)
├── .env / .env.example             # Shared secrets (lives at root)
│
├── repo-a/                         # Independent git repo
├── repo-b/                         # Independent git repo
│
├── deploy/                         # Cross-repo: nginx, infra configs, deploy scripts
├── scripts/                        # Cross-repo: shared tooling
├── tools/                          # Cross-repo: shared CLI utilities
│
├── docs/                           # Cross-repo documentation ONLY
│   ├── design/                     #   System-wide architecture specs
│   ├── research/                   #   Cross-cutting investigations
│   ├── runbooks/                   #   Deploy, ops, incident response

From zning1994/brainharness-docs, MIT.