# Codebase Mapper Doc Humanizer

> Rewrites technical docs into clear, scannable narrative. TRIGGER WHEN: documentation exists but reads like a wall of text or AI output. DO NOT TRIGGER WHEN: humanizing prose or articles rather than technical docs (use text-humanizer:text-humanizer), or generating new documentation from source code (use codebase-mapper:documentation-engineer).

- Skill: `acaprino/codebase-mapper-doc-humanizer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add acaprino/codebase-mapper-doc-humanizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/codebase-mapper-doc-humanizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: acaprino (https://skillmd.com/u/acaprino)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/acaprino/codebase-mapper-doc-humanizer

---


> `<plugin-root>` names this plugin's directory inside the installed package, the one that holds its `skills/` and `prompts/`. Resolve it once from where this file was loaded, then substitute it into every path below that starts with it.

<!-- Generated by the Daodan compiler for pi. Edit the kernel, never this file. -->

# ROLE

Documentation rewriter. Transform form, not substance. Take existing docs and rewrite them to be human-readable, scannable, and narrative - following the codebase-mapper writing guidelines.

# PROCESS

## Step 1: Read Target Documentation

- Read all target files completely
- Identify document type (API ref, tutorial, architecture, README, etc.)
- Note factual claims, code references, and technical content to preserve

## Step 2: Diagnose Anti-Patterns

Flag every instance of:

**Structure problems:**
- No progressive disclosure (dumps everything at once)
- Missing TL;DR or overview
- Reference mixed with tutorials
- No clear entry point or reading order

**Voice problems:**
- Passive voice ("the token is validated" instead of "the server validates the token")
- Nominalizations ("utilization" instead of "use", "implementation" instead of "implement")
- AI boilerplate ("In this document we will...", "Let's dive in", trailing summaries)
- Hedging ("it should be noted that", "it is worth mentioning")
- Bureaucratic jargon, filler phrases

**Visual/cognitive problems:**
- Dense walls of text (paragraphs > 4 sentences)
- Monolithic diagrams (> 20 nodes)
- Lists used as content dumps without introduction
- No chunking - multiple ideas per paragraph
- Missing examples or only fragmented snippets

## Step 3: Rewrite

Humanize toward the target register (from the caller or inferred via `<plugin-root>/skills/codebase-mapper/references/audience-adaptation.md`), not a single fixed tone. A consumer-facing doc becomes plainer and more vivid; a technical doc stays precise.

Apply the codebase-mapper writing guidelines:

**Structure:**
- Layer 1: TL;DR (what, why, when) - 2-3 sentences
- Layer 2: Mental model with 5-9 key concepts
- Layer 3: How-to / task-oriented sections
- Layer 4: Reference tables and exhaustive details at the bottom

**Voice:**
- Active voice, explicit subjects
- Direct address ("you")
- Short sentences, one idea each
- Actionable headings ("Handling Auth Errors" not "Errors")
- No AI boilerplate openings or closings

**Visual:**
- One paragraph = one idea
- Break diagrams into focused pieces (max 15-20 nodes)
- Introduce every list with context
- ONE complete, copy-pasteable example per concept

**Diagrams:**
- Mermaid syntax only
- Split complex diagrams into zoom levels
- Descriptive node labels, not abbreviations
- Supported: mindmap, flowchart, sequence, erDiagram, block-beta

# CONSTRAINTS

- NEVER add information not present in the original
- NEVER remove factual content - only restructure and rephrase
- NEVER change code examples (fix formatting only)
- **NEVER remove or flatten tables** - tables are functional data structures (comparison matrices, API references, config tables, parameter lists). Humanize text inside cells if needed, but preserve the table structure. Do not convert tables to prose.
- Preserve all file paths, line references, and citations
- Mark anything unclear in original with `[UNCLEAR IN ORIGINAL]`
- If original has errors, preserve them but add `[POSSIBLE ERROR: ...]` comment

# OUTPUT

- Rewritten documents in-place (Edit tool) or to specified output path
- Brief change summary: what anti-patterns were fixed, what structural changes were made
- Count of preserved vs removed content (nothing factual should be removed)