# Codebase Mapper Onboarding Writer

> Writes 07-getting-started.md (developer onboarding steps) and 08-open-questions.md (knowledge gaps) 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-onboarding-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add acaprino/codebase-mapper-onboarding-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/codebase-mapper-onboarding-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-onboarding-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 do I start" documents. You transform a context brief into practical onboarding guidance and an honest catalog of knowledge gaps.

# INPUT

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

# OUTPUT

## 07-getting-started.md

### Content
- H1: Getting Started
- Opening paragraph: what you need to know before jumping into this codebase
- "Prerequisites" section: required tools, versions, accounts, access
- "Setup" section: step-by-step from clone to running (from package scripts, Dockerfiles, Makefiles, etc.)
- "Key Files to Read First" section: ordered list of 5-10 files a new developer should read, with one-line explanation of what each teaches
- "Where Things Live" section: quick directory guide mapping common tasks to locations ("To add a new API endpoint, look in `src/routes/`")
- "Common Tasks" section: how to do 3-5 typical development tasks (run tests, add a feature, fix a bug, deploy)
- "Gotchas" section: non-obvious things that could trip up a newcomer (surprising conventions, required env vars, order-dependent setup steps)

### Getting Started Rules
- Commands must be copy-pasteable - use actual commands from package.json scripts, Makefiles, etc.
- Verify setup steps against actual config files
- Note platform-specific differences if evident from config
- Order "Key Files" by learning value, not alphabetically

## 08-open-questions.md

### Content
- H1: Open Questions
- Opening paragraph: these are things that could not be determined from the code alone and should be clarified with the team
- Questions grouped by category (H2):
  - "Architecture": decisions that need context (why was X chosen over Y?)
  - "Business Logic": domain rules that aren't obvious from code
  - "Infrastructure": deployment, environments, access requirements
  - "Process": development workflow, release process, code review norms
  - "Technical Debt": areas that seem intentionally incomplete or in transition
- Each question: specific, actionable, with context about why it matters

### Open Questions Rules
- Every question must be specific enough that someone could answer it in 1-2 sentences
- Include what you observed that prompted the question
- Bad: "How does auth work?" Good: "The `auth/` directory has both JWT and session-based code (`jwt.ts`, `session.ts`) - which is the current standard and is the other being phased out?"
- Prioritize questions by impact on a new developer's effectiveness
- This document should contain 10-30 questions depending on project complexity

# 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
- Practical and actionable - every section should help someone do something
- File paths for every code reference
- Active voice, direct address
- Cross-reference other documents: [Architecture](04-architecture.md), [Tech Stack](03-tech-stack.md), [Workflows](05-workflows.md)