[Claude Code Prompt Library] Add MAP prompt-pattern catalog and prompt-improvement audit

[azalio]

Source

Attached source: /Users/azalio/.codex/attachments/facea5c7-2bda-4efa-a841-c10cd127c82f/pasted-text.txt, a captured Claude Code docs page for Prompt library.

Official docs index checked first as requested by the source header: https://code.claude.com/docs/llms.txt lists the Prompt library page at https://code.claude.com/docs/en/prompt-library.md and related docs for common workflows, best practices, memory, skills, hooks, MCP, output styles, goal, and permissions.

Source-specific idea used here: Claude Code's Prompt Library is not just a list of commands. It packages repeatable prompts as a structured catalog with SDLC phase, category, role tags, needed integrations, fillable slots, copyable prompt text, "why this works" rationale, next-step links, and a short pattern guide. The user also explicitly asked to check whether MAP prompts can be improved from this.

Relevant source takeaways

• Prompt examples are grouped by SDLC phase (discover, design, build, ship, operate) and category (Understand, Plan, Implement, Test, Review, etc.), which helps users pick the right prompt without knowing internal command names.
• Prompts include role tags such as product, design, docs, marketing, security, ops. That matters because the same workflow can need a different framing for PM/design/docs/security users.
• Entries include needs metadata for external prerequisites such as gh, browser rendering, databases/log stores, or trackers. This avoids prompts that look copyable but fail because the operator lacks a connector/tool.
• The page explains reusable prompt patterns: describe the outcome rather than exact steps; give the agent a way to verify its work; point at references; state measurable targets; provide artifacts such as logs/screenshots/CSV; specify desired answer format/audience.
• The strongest MAP-relevant lesson is not to rewrite prompts blindly. A prompt library should preserve why a pattern works, and prompt changes should be checked against measurable outcomes rather than treated as prose cleanup.

Repo evidence

• README.md:21-36 gives a concise golden path and command sequence, but it is command-centric (/map-plan, /map-efficient, /map-check, /map-review, /map-learn) rather than a role/tagged prompt catalog with fillable examples and rationale.
• README.md:131-154 lists core commands and canonical flows. This helps users choose a MAP command, but it does not show task-shaped prompts like "plan a multi-file refactor before touching code", "review uncommitted changes before commit", "turn correction into a rule", or role-specific variants.
• docs/USAGE.md:15-30 documents canonical flows. It has examples, but not a source-like catalog indexed by phase/category/role/needs.
• MAP already has strong internal prompt engineering surfaces. README.md:169-176 documents calibrated workflow effort, mutation boundaries, XML prompt envelopes, token/ROI reports, retry quarantine, and run health. docs/ARCHITECTURE.md:963-973 documents review prompt ordering probes, review-bundle-first context, acceptance coverage, prior-stage consumption, evidence-first review contracts, and JSON prompt contract checks.
• docs/SKILL-EVAL.md:8-20 shows skill-eval measures trigger accuracy and tunes only description: frontmatter, not whole prompt bodies.
• docs/whole-skill-optimization-notes.md and docs/whole-skill-optimization-flow.md already describe outcome-quality/A-B methods for prompt/body changes. This means broad internal prompt rewrites should be routed through that measurement path, not performed as documentation-inspired copy edits.

Existing issue search

Commands/searches used:

• gh issue list --state all --limit 120 --search "prompt library OR prompt catalog OR prompt recipes OR prompt examples OR prompt quality OR improve prompts OR user prompts OR role-based prompts" returned no matches.
• gh issue list --state all --limit 120 --search "agent prompt OR prompt layering OR XML prompt OR JSON prompt OR output style OR verification loop OR measurable target" returned no direct duplicate.
• gh issue list --state all --limit 120 --search "whole-skill optimization OR skill-eval OR trigger accuracy OR outcome quality OR prompt body OR description tuning" surfaced unrelated /map-efficient: parallel-wave execution shipped but dark — sequential by default at every gate #303 only.

Close related work checked:

• Existing skill-eval / /map-skill-eval covers trigger accuracy and cost for skill descriptions, not user-facing prompt recipes or source-pattern coverage.
• Existing whole-skill optimization docs cover how to A/B prompt/body changes, but they are a method, not a source-derived audit of MAP's prompt surfaces or a user-facing prompt library.
• Existing XML/JSON prompt contract work covers internal prompt robustness, not discoverability for users or a catalog of role/task prompt patterns.

Why this is not already covered

MAP tells users which command to run and has deep internal prompt controls, but it lacks a structured prompt-pattern layer that answers: "What should I type for this kind of work, why does that prompt work, what tool prerequisites does it assume, and which MAP surface should it route to?"

It also lacks a compact audit that maps the Prompt Library's generic patterns to MAP's active prompts and explicitly decides which internal prompt improvements are worth A/B evaluation. Without that, source-inspired prompt edits risk becoming prose churn or weakening carefully tested internal contracts.

Problem

New MAP users see commands and canonical flows, not a prompt library. They may still issue vague ad-hoc prompts or choose the wrong surface because the docs do not translate common tasks and roles into MAP-shaped prompt recipes. Separately, maintainers have no source-derived checklist for prompt improvement opportunities that distinguishes safe docs/examples from risky internal agent prompt edits requiring outcome eval.

Proposed slice

Add a MAP prompt-pattern catalog and improvement audit inspired by Claude Code Prompt Library.

Concrete first slice:

• Add a docs page or generated reference such as docs/PROMPT_LIBRARY.md with a small curated set of MAP prompt recipes grouped by phase/category/role:
  • Discover/Understand: codebase overview, behavior lookup, impact-before-delete.
  • Design/Plan: multi-file refactor planning, spec-by-interview, edge-case mapping.
  • Build/Test: implement from existing pattern, test-first flow, issue end-to-end.
  • Review/Ship: review uncommitted changes, PR/release note workflows.
  • Operate/Debug: failing test/build error/incident investigation mapped to /map-debug or /map-review.
• For each recipe include: prompt text, slots/placeholders, recommended MAP command/skill, prerequisites (gh, browser, tracker, db/log store), why it works, and what artifact/check should prove completion.
• Add a prompt-pattern audit table for active MAP prompts with source-derived patterns: outcome-first framing, explicit verification loop, reference/artifact handling, measurable target, output format/audience, prerequisite disclosure, and memory/learning follow-up.
• For user-facing docs/examples, allow direct docs improvement. For internal agent/skill prompt body changes, require an explicit A/B or whole-skill eval plan unless the change is purely documentation or trigger-description tuning.
• Link the catalog from README/USAGE so users have a quick "what should I type?" surface, not only command reference.

Acceptance criteria

• A new or updated docs page contains at least 12 MAP-specific prompt recipes across at least 5 categories and 3 roles, each with prompt, slots, MAP surface, prerequisites, why-it-works, and verification/check guidance.
• README or USAGE links to the prompt catalog from the quick-start/core-command area.
• The audit table classifies source prompt patterns as implemented, docs-only gap, or internal-prompt eval candidate, with repo evidence for each classification.
• No internal agent/skill prompt body is changed without either an existing test/fixture proving behavior is unaffected or a documented A/B/whole-skill eval plan.
• Generated template invariants are respected if shipped docs/templates are touched: edit template source first and run render/check-render in implementation.

Guardrails

• Do not copy the Claude Code prompt library wholesale; translate only MAP-relevant patterns and cite the source.
• Do not add a heavy UI unless there is evidence docs are insufficient; a Markdown catalog is the first slice.
• Do not rewrite active Actor/Monitor/Decomposer prompts just because a generic prompt sounds nicer. MAP prompts are load-bearing and must be evaluated.
• Do not duplicate skill-eval: trigger-description tuning remains owned by mapify skill-eval; this issue adds user-facing recipes and a prompt-pattern audit.
• Do not add recipes that require unavailable tools without labeling prerequisites.