doc-regen

---
name: doc-regen
description: "DevHub auto-doc regenerator — AST-based API/subsystem documentation refresh. Use when the user says 'regen docs for {subsystem}', 'update API docs', 'auto-doc {path}', or 'refresh devhub docs'."
mode: [personal, all]
effort: low
see_also: [portal-sync, feature-update, code-review]
thinking_mode: adaptive
version: 1.0.0
tier: [dev, admin]
category: devhub
emoji: "📄"
triggers:
  - "regen docs"
  - "update API docs"
  - "auto-doc"
  - "refresh docs"
  - "regenerate docs"
  - "devhub docs"
  - "document subsystem"
---

# Doc Regen

AST-based documentation regeneration for DevHub. Scans Python/TypeScript source,
extracts docstrings + endpoint signatures, and updates the DevHub docs index.

## When to Use

- After adding/modifying backend endpoints or services
- After a major refactor that changes API shape
- Before a release tag (ensure docs reflect HEAD)
- When DevHub `/docs` shows stale endpoint signatures

## Commands

```bash
# Regen docs for a specific subsystem
python scripts/devhub-docs-gen.py --subsystem instruments
python scripts/devhub-docs-gen.py --subsystem procurement
python scripts/devhub-docs-gen.py --subsystem devhub

# Regen from a specific path
python scripts/devhub-docs-gen.py --path backend/app/api/endpoints/instruments.py

# Regen all (slower, use sparingly)
python scripts/devhub-docs-gen.py --all

# Dry-run (preview what would be written)
python scripts/devhub-docs-gen.py --subsystem instruments --dry-run

# Push generated docs to DevHub (auto-done unless --no-push)
python scripts/devhub-docs-gen.py --subsystem instruments --push
```

> ⚠️ **T12 dependency**: `scripts/devhub-docs-gen.py` is implemented in T12.
> This skill is authoritative — when T12 lands, the command is drop-in.

## Process

### Step 1 — Resolve subsystem path

```bash
# Map subsystem name → source directories
# instruments   → backend/app/api/endpoints/instruments.py + services/instrument_service.py
# procurement   → backend/app/api/endpoints/procurement/ + services/procurement/
# devhub        → backend/app/api/endpoints/devhub/ + frontend-devhub/src/
```

### Step 2 — Run AST extraction

```bash
python scripts/devhub-docs-gen.py --subsystem "${SUBSYSTEM}" --dry-run
# Review output, then run for real:
python scripts/devhub-docs-gen.py --subsystem "${SUBSYSTEM}"
```

### Step 3 — Verify output

```
📄 Doc regen: instruments
  Scanned: 3 files (847 LOC)
  Extracted: 12 endpoints, 8 models, 3 services
  Generated: docs/api/instruments.md (NEW), docs/services/instrument-service.md (UPDATED)
  Skipped: 2 private functions (_build_filter, _normalize_units)
  Pushed to DevHub: ✅ /api/v1/devhub/docs/instruments → 200 OK
```

## Guardrails (per performance-discipline Rule 4)

- **Skip files < 30 LOC** — noise prevention
- **Skip `_private` functions** — internal API, not doc-worthy
- **Tag generated output** with `<!-- auto-generated by devhub-docs-gen.py -->` header
- **Never auto-commit** to main — always review generated docs before push
- **No hallucination**: only extract what's explicitly in source AST, never infer

## HITL Gates

- **`--all` flag**: Confirm before full regeneration (can touch 100+ files)
- **Generated docs to main**: Review PR via `code-review` skill before merging

## Error Handling

| Error | Action |
|-------|--------|
| `scripts/devhub-docs-gen.py` not found | T12 not yet landed — note in report, defer |
| ImportError / SyntaxError in source | Show error, skip that file, continue |
| DevHub push 422 (schema mismatch) | Run `portal-sync --scope docs` to re-index schema |
| No docstrings found | Warn user — doc quality low, suggest adding docstrings |

## Subsystem Registry

| Subsystem | Source paths |
|-----------|-------------|
| `instruments` | `backend/app/api/endpoints/instruments.py`, `services/instrument_service.py` |
| `procurement` | `backend/app/api/endpoints/procurement/` |
| `devhub` | `backend/app/api/endpoints/devhub/`, `frontend-devhub/src/` |
| `estimate` | `backend/app/api/endpoints/estimate.py`, `services/estimate_service.py` |
| `import` | `backend/app/api/endpoints/import_pipeline.py` |

Add new subsystems to `scripts/devhub-docs-gen.py` `SUBSYSTEM_MAP` dict.

## Related

- `portal-sync` — Push generated docs to DevHub after regen
- `code-review` — Review generated docs PR before merging to main
- T12 (`scripts/devhub-docs-gen.py`) — AST extractor implementation