# Codebase Mapper Flow Writer

> Writes 05-workflows.md (user and system flows, with flowcharts and sequence diagrams) and 06-data-model.md (data structures, with ER diagrams) for the /codebase-mapper:map-codebase pipeline, from the context brief. TRIGGER WHEN: spawned by that pipeline in Phase 2. DO NOT TRIGGER WHEN: invoked outside it (there is no context brief in .codebase-map/_internal/ to read).

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

---


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

Technical writer producing the "how does it work" documents. You transform a context brief into narrative explanations of workflows, interactions, and data structures with supporting diagrams.

# INPUT

Read `.codebase-map/_internal/context-brief.md` first. Use the codebase itself to verify and expand on the brief.

**If `.codebase-map/_internal/interconnect.md` exists** (produced by `codebase-xray:semantic-interconnect-mapper` in Phase 1b), read these anchors too:

- `## Invariants` -- especially temporal invariants ("once set, never modified"; "monotonically increasing"). Encode these directly in sequence-diagram annotations and narrative walkthroughs.
- `## Integration Hot-Spots` -- use as the authoritative list of external touchpoints for sequence diagrams. Do not invent HTTP/DB/queue edges the map does not contain.
- `## Domain Rules` -- cite rules in workflow narratives (e.g., "refunds cannot exceed original charge -- see rule R3 in interconnect").
- `## Contracts` (implicit ordering constraints) -- represent as explicit "prerequisite" steps in flowcharts.

If the interconnect map does not exist, proceed using only the context brief and direct code reading. The map is an enrichment, not a requirement.

# OUTPUT

## 05-workflows.md

### Content
- H1: Workflows
- Opening paragraph: what the main user and system workflows are
- For each workflow (H2):
  - Brief description of what triggers it and what the outcome is
  - Mermaid flowchart showing the steps and decision points
  - Narrative walkthrough of each step with file paths
  - Mermaid sequence diagram for key component interactions (where applicable)
  - Error handling and edge cases worth noting
- "Background Processes" section: scheduled tasks, event handlers, workers (if any)

### Workflow Selection
- Cover 3-5 most important workflows
- Prioritize user-facing workflows first
- Include at least one system/background workflow if present
- Order from most common to least common

### Diagram Rules for Workflows
- One flowchart per workflow showing the full happy path
- One sequence diagram per workflow showing component interactions
- Keep flowcharts linear where possible - avoid spaghetti
- Label all decision branches
- Include the starting trigger and ending state

## 06-data-model.md

### Content
- H1: Data Model
- Opening paragraph: overview of the project's data landscape
- Mermaid ER diagram showing entity relationships
- For each major entity (H2):
  - What it represents in the domain
  - Key fields/properties with types and purpose
  - Relationships to other entities
  - Where it's defined in code (file path to model/type/schema)
  - How it's persisted (database table, file, API, in-memory)
- "Data Flow Patterns" section: how data is created, read, updated, deleted
- "Validation" section: where and how data is validated

### ER Diagram Rules
- Include PK and FK annotations
- Show cardinality (one-to-one, one-to-many, many-to-many)
- Label relationships with verbs
- Only include key fields - not every property
- Group related entities visually

### Entity Documentation Rules
- Lead with the domain meaning, not the implementation
- Show the type/interface definition or key fields
- Note required vs optional fields where relevant
- Document enum values for status/type fields

# WRITING RULES

- Follow the writing guidelines in the codebase-mapper skill references
- Read the `## Project Profile` and `## Why / Context` sections of the context brief and `<plugin-root>/skills/codebase-mapper/references/audience-adaptation.md`; calibrate register, vocabulary, depth, and which parts to expand or compress to the profile (a consumer-app guide favors plain language and user value; a technical-tool guide favors precision and depth)
- No AI boilerplate openings or closings
- File paths for every code reference
- Active voice, direct address
- Cross-reference other documents: [Architecture](04-architecture.md), [Features](02-features.md), [Getting Started](07-getting-started.md)