Publications Workflow Prompts¶

Prompts for generating, iterating on, and releasing documentation using FCC personas. Each prompt uses R.I.S.C.E.A.R. activations and targets a specific publication task: drafting chapters, review cycles, diagram generation, cross-references, release notes, executive summaries, and audience translation. Twelve prompts total covering the full documentation lifecycle.

Table of Contents¶

Drafting a New Chapter (RC + BC + DE)
Reviewing an Existing Chapter (BV + DE)
Generating Diagrams from Descriptions (BC + UAA)
Creating Consistent Cross-References (DE + BV)
Updating Documentation After Code Changes (RC + BC + DE)
Writing Release Notes (DE + SMC + RC)
Creating Executive Summaries from Technical Docs (RC + DE)
Translating Jargon for Different Audiences (DE + UAA)
Chapter Outline Authoring (BC + RC)
Style-Guide Compliance Pass (BV + DE)
Tutorial Learning-Objective Mapping (DE + BC)
Publication Retrospective (DE + BV + CO)

1. Drafting a New Chapter¶

Personas: Research Crafter (RC) + Blueprint Crafter (BC) + Documentation Evangelist (DE)¶

Scenario: Produce a first-draft chapter for a technical book or guide.

You are coordinating three personas to draft a new chapter.

CHAPTER TITLE: {title}
BOOK/GUIDE: {which publication, which position in ToC}
TARGET AUDIENCE: {beginner / intermediate / advanced}
WORD-COUNT TARGET: {e.g., 3000-4000}

TEAM:
- Research Crafter (RC): gather source material
- Blueprint Crafter (BC): chapter outline and narrative arc
- Documentation Evangelist (DE): prose authoring and style enforcement

PHASE 1 -- RESEARCH (RC, Find):
Gather:
- Prior chapters covering related material (for cross-reference)
- Source code, examples, or APIs covered
- External references: papers, blog posts, specs
- Open questions the chapter must answer

Produce a 400-word research brief with citations and open questions.

PHASE 2 -- OUTLINE (BC, Create):
Produce chapter outline:
- 3-5 learning objectives (Bloom's taxonomy levels)
- 5-8 sections with 1-sentence summaries
- 2-3 worked examples
- 1 diagram placement per section max
- End-of-chapter exercises (3-5)

PHASE 3 -- DRAFT (DE, Create):
Write prose against the outline. Style:
- Short paragraphs (3-5 sentences)
- Concrete examples within 3 paragraphs of any concept
- No headings deeper than h3
- Code examples executable as-is
- Cross-links to related chapters/docs

CONSTRAINTS:
- Word count within 10% of target
- Every code example must run in a fresh environment
- No jargon introduced without a 1-sentence definition
- All diagrams use the FCC color conventions (Mermaid classDef)

OUTPUT: Complete chapter draft with front matter, prose, code blocks,
diagrams, exercises, and cross-references. Ready for review.

Expected Output: Chapter markdown file with front matter, 5-8 sections, worked examples, diagrams, and exercises.

2. Reviewing an Existing Chapter¶

Personas: Blueprint Validator (BV) + Documentation Evangelist (DE)¶

Scenario: Review a draft chapter for correctness, style, and structural quality.

You are coordinating two personas to review a chapter draft.

CHAPTER: {path}
REVIEW DIMENSIONS: technical accuracy, pedagogical flow, style compliance

TEAM:
- Blueprint Validator (BV): technical and structural critique
- Documentation Evangelist (DE): voice, style, clarity

BV RESPONSIBILITIES:
1. Verify code examples execute in clean env
2. Verify claims against authoritative sources
3. Score structural coherence (1-5 per section)
4. Flag missing cross-links, broken references
5. Flag logical gaps or unjustified conclusions

DE RESPONSIBILITIES:
1. Check style-guide compliance (tone, voice, person)
2. Flag jargon introduced without definition
3. Check paragraph length and sentence complexity
4. Verify learning objectives map to content
5. Check consistency with prior chapters

OUTPUT FORMAT:

## Review: {chapter_title}
**Overall Score:** {1-5}
**Technical Accuracy:** findings with line numbers
**Structural Coherence:** section-by-section scores
**Style Compliance:** findings with line numbers
**Cross-Reference Health:** broken, missing, suggested links
**Blockers:** must-fix before publish
**Suggestions:** nice-to-have improvements

Expected Output: Structured review with blockers and suggestions, line-numbered.

3. Generating Diagrams from Descriptions¶

Personas: Blueprint Crafter (BC) + User Advocate Architect (UAA)¶

Scenario: Translate a textual description into a Mermaid diagram following FCC conventions.

You are coordinating two personas to generate a diagram.

DESCRIPTION: {textual description of system, flow, or relationship}
DIAGRAM TYPE: flowchart / sequence / class / entity-relationship / state

TEAM:
- Blueprint Crafter (BC): diagram structure and semantics
- User Advocate Architect (UAA): reader-facing clarity

BC RESPONSIBILITIES:
1. Identify nodes (entities) and edges (relationships)
2. Pick diagram type matching the content
3. Apply FCC color conventions via classDef:
   - core personas: fill:#fff3e0, stroke:#e65100
   - governance: fill:#fce4ec, stroke:#880e4f
   - integration: fill:#e8f5e9, stroke:#1b5e20
   - decision/outcome: fill:#c8e6c9, stroke:#2e7d32
4. Keep node count <= 12 for comprehension

UAA RESPONSIBILITIES:
1. Ensure labels are reader-meaningful, not jargon
2. Add subgraph groupings for related nodes
3. Verify top-to-bottom or left-to-right reading order
4. Add a 1-sentence caption under the diagram

OUTPUT: Mermaid diagram in a fenced code block, followed by a caption.
If the diagram exceeds 12 nodes, split into 2-3 sub-diagrams.

Expected Output: Mermaid code block with FCC coloring, caption, and optional splits.

4. Creating Consistent Cross-References¶

Personas: Documentation Evangelist (DE) + Blueprint Validator (BV)¶

Scenario: Audit and update cross-references across a documentation set.

You are coordinating two personas for cross-reference maintenance.

SCOPE: {directory or set of files}

DE RESPONSIBILITIES:
1. Identify all cross-reference targets in scope
2. Standardize link syntax: [text](relative/path.md)
3. Enforce naming conventions in link text
4. Add bidirectional links where appropriate

BV RESPONSIBILITIES:
1. Verify every link resolves (no 404s)
2. Flag circular references
3. Flag under-linked pages (<2 inbound links)
4. Flag over-linked pages (>20 inbound; may need split)

OUTPUT:
- Updated files with corrected links
- Cross-reference graph (optional mermaid)
- Orphan list (pages with 0 inbound links)
- Hub list (pages with 10+ inbound links; verify intentional)

Expected Output: Updated files with clean cross-references + link-health report.

5. Updating Documentation After Code Changes¶

Personas: RC + BC + DE¶

Scenario: Sync documentation with recent code changes.

You are coordinating three personas to sync docs with code.

INPUT: git diff or changelog covering the code delta
SCOPE: public API surface, CLI flags, config format, behavior changes

TEAM:
- Research Crafter (RC): analyze code delta for doc-affecting changes
- Blueprint Crafter (BC): plan doc updates
- Documentation Evangelist (DE): execute doc updates

RC RESPONSIBILITIES:
1. Enumerate: new symbols, removed symbols, renamed symbols
2. Identify changed signatures (parameters, return types)
3. Identify changed behaviors (semantics even if signature stable)
4. Map each to current doc locations

BC RESPONSIBILITIES:
1. Build update checklist: files to update, sections to add/remove
2. Identify migration-guide needs (breaking changes)
3. Identify new example needs
4. Sequence updates to minimize broken-link windows

DE RESPONSIBILITIES:
1. Execute checklist, updating prose and examples
2. Add deprecation notices with target-removal versions
3. Publish migration guide for breaking changes
4. Update changelog

OUTPUT:
- Doc update diff
- Migration guide (if applicable)
- Changelog entry
- Updated examples verified to execute

Expected Output: PR containing doc updates, migration guide, and changelog entry.

6. Writing Release Notes¶

Personas: DE + SMC + RC¶

Scenario: Produce release notes for a software version.

You are coordinating three personas to write release notes.

VERSION: {semver}
CHANGELOG SOURCE: {path to raw changelog or git log}

TEAM:
- Documentation Evangelist (DE): prose and audience translation
- SAFe Metrics Crafter (SMC): counts and highlights
- Research Crafter (RC): impact analysis

RC RESPONSIBILITIES:
1. Identify headline changes (what users care about most)
2. Flag breaking changes
3. Identify security fixes (for separate callout)
4. Map commits to user-visible outcomes

SMC RESPONSIBILITIES:
1. Count changes by category (features, fixes, docs, refactors)
2. Compute delta (n files changed, n LOC)
3. Identify contributors (for acknowledgments)

DE RESPONSIBILITIES:
1. Produce release-note sections:
   - Headline (2-3 sentences)
   - Highlights (3-5 most impactful changes, 1-2 sentences each)
   - Breaking Changes (if any; with migration guidance)
   - Features (list with 1-sentence each)
   - Fixes (list)
   - Security (separate section if applicable)
   - Contributors
   - Upgrade Instructions

CONSTRAINTS:
- Headline is user-outcome oriented, not commit-message oriented
- Every breaking change has a migration link
- Security fixes come before features
- Under 1500 words total

OUTPUT: Release notes markdown ready for publication.

Expected Output: Release notes with 8 sections, ready to publish.

7. Creating Executive Summaries from Technical Docs¶

Personas: Research Crafter (RC) + Documentation Evangelist (DE)¶

Scenario: Compress a multi-page technical document into a 1-page executive summary.

You are coordinating two personas to produce an executive summary.

SOURCE: {path to technical document}
TARGET LENGTH: 300-400 words
TARGET AUDIENCE: non-technical executive

TEAM:
- Research Crafter (RC): extract key findings
- Documentation Evangelist (DE): translate for audience

RC RESPONSIBILITIES:
1. Identify the document's single core thesis
2. List 3-5 supporting findings with evidence
3. Extract quantitative claims (numbers, dates, percentages)
4. Identify 1-2 risks or trade-offs

DE RESPONSIBILITIES:
1. Open with "What" and "Why it matters" in 2 sentences
2. Translate all jargon to business language
3. Replace technical metrics with outcome metrics
4. Close with specific asks or decisions required

OUTPUT STRUCTURE:
## Executive Summary: {title}
**Bottom line:** 1 sentence
**Why it matters:** 1 sentence
**Key findings:** 3-5 bullets
**Trade-offs:** 1-2 bullets
**Recommendation:** 1 sentence
**Decision requested:** 1 sentence

CONSTRAINTS:
- No jargon without business-language translation
- Every number has context (vs last period, vs target)
- No section longer than 4 bullets

Expected Output: One-page executive summary with clear ask/decision.

8. Translating Jargon for Different Audiences¶

Personas: DE + UAA¶

Scenario: Rewrite technical content for a new audience (e.g., engineers -> product managers).

You are coordinating two personas to translate content for a new audience.

SOURCE: {path to original content}
SOURCE AUDIENCE: {e.g., backend engineers}
TARGET AUDIENCE: {e.g., product managers}

TEAM:
- Documentation Evangelist (DE): voice and style
- User Advocate Architect (UAA): audience modeling

UAA RESPONSIBILITIES:
1. Model target audience: prior knowledge, vocabulary, concerns
2. Identify which source concepts need reframing vs removal
3. Identify analogies or examples native to target audience
4. Set appropriate depth (what details to keep, drop)

DE RESPONSIBILITIES:
1. Rewrite retaining core meaning at target vocabulary
2. Replace source-domain examples with target-domain examples
3. Remove source-only concerns (e.g., perf details for PMs)
4. Add target-specific concerns (e.g., business outcomes)

OUTPUT: Rewritten content + translation notes explaining:
- What was kept
- What was reframed (with before/after)
- What was removed and why
- What was added for target audience

Expected Output: Audience-appropriate version + translation notes for review.

9. Chapter Outline Authoring¶

Personas: Blueprint Crafter (BC) + Research Crafter (RC)¶

Scenario: Produce a chapter outline before drafting begins.

You are coordinating two personas to outline a new chapter.

CHAPTER TITLE: {title}
CONTEXT: {book, position, prior chapters}
TARGET LEVEL: {beginner / intermediate / advanced}

TEAM:
- Blueprint Crafter (BC): outline structure and narrative
- Research Crafter (RC): source material inventory

RC RESPONSIBILITIES:
1. List available source material (prior chapters, code, external refs)
2. Identify prerequisite knowledge readers need
3. Note concepts introduced here vs assumed from prior chapters

BC RESPONSIBILITIES:
1. Define 3-5 learning objectives (Bloom's verbs: explain, apply, analyze, design)
2. Design 5-8 sections in logical progression
3. Identify worked-example placements (2-3)
4. Identify diagram placements (2-4)
5. Design exercises (3-5) tied to learning objectives

OUTPUT: Outline YAML:
- title
- learning_objectives: list
- prerequisites: list
- sections: list with name, summary, est_words
- worked_examples: list
- diagrams: list with placement
- exercises: list with target objective
- est_total_words

Expected Output: Structured outline ready to pass to a DE for drafting.

10. Style-Guide Compliance Pass¶

Personas: Blueprint Validator (BV) + Documentation Evangelist (DE)¶

Scenario: Enforce style-guide compliance across a set of docs.

You are coordinating two personas for a style-guide compliance pass.

SCOPE: {directory or file set}
STYLE GUIDE: {path to style guide}

BV RESPONSIBILITIES:
1. Lint against style-guide rules (voice, tense, person)
2. Flag jargon introduced without definition
3. Flag passive voice where active is required
4. Flag sentences longer than 35 words
5. Flag paragraphs longer than 5 sentences

DE RESPONSIBILITIES:
1. Fix flagged issues
2. Harmonize voice across contributors
3. Ensure consistent capitalization of product terms
4. Ensure consistent link text conventions

OUTPUT:
- Updated files
- Compliance report: rule-by-rule, before/after counts
- Exceptions list (with justifications)

Expected Output: Compliant docs + compliance report.

11. Tutorial Learning-Objective Mapping¶

Personas: DE + BC¶

Scenario: Verify tutorial content matches declared learning objectives.

You are coordinating two personas to audit learning-objective alignment.

TUTORIAL: {path}

TEAM:
- Documentation Evangelist (DE): content traversal
- Blueprint Crafter (BC): objective-content mapping

DE RESPONSIBILITIES:
1. Extract all learning objectives from tutorial front matter
2. List all sections with their topics
3. Map sections to objectives

BC RESPONSIBILITIES:
1. For each objective: is there content supporting it?
2. For each section: which objective(s) does it support?
3. Flag orphan objectives (no supporting content)
4. Flag orphan content (not mapped to any objective)
5. Flag over-coverage (objective addressed in 5+ sections)

OUTPUT: Alignment report with mapping matrix + recommendations.

Expected Output: Objective-content matrix + gap report.

12. Publication Retrospective¶

Personas: DE + BV + CO¶

Scenario: Retrospect after publishing a major doc deliverable.

You are coordinating three personas for a publication retrospective.

DELIVERABLE: {book, tutorial set, or doc refresh}
TIMEFRAME: 30-90 days post-publish

TEAM:
- Documentation Evangelist (DE): reader feedback synthesis
- Blueprint Validator (BV): quality retrospective
- Collaboration Orchestrator (CO): process retrospective

DE RESPONSIBILITIES:
1. Gather reader feedback: issue tracker, surveys, social
2. Categorize: comprehension, accuracy, completeness, navigation
3. Identify recurring themes

BV RESPONSIBILITIES:
1. Audit sample pages for quality drift
2. Verify code examples still execute
3. Check cross-reference health
4. Identify areas needing refresh

CO RESPONSIBILITIES:
1. Reflect on production process (what worked, what hurt)
2. Identify handoff friction
3. Capture lessons for next publication cycle

OUTPUT: Retrospective doc with:
- Reader feedback themes (with evidence)
- Quality audit findings
- Process improvements for next cycle
- Committed action items with owners

Expected Output: Retrospective report with action items.

Combining Prompts¶

These prompts chain naturally:

Chapter lifecycle: Outline (#9) -> Draft (#1) -> Review (#2) -> Style Pass (#10) -> Cross-refs (#4)
Release lifecycle: Sync docs with code (#5) -> Release notes (#6) -> Executive summary (#7)
Quality lifecycle: Review (#2) -> Cross-refs (#4) -> Style Pass (#10) -> Retrospective (#12)

Next Steps¶

Building Your Own Book -- full book creation workflow
Contributing to Books -- contributing to the 3-book series
Persona Interaction Prompts -- single-persona prompts
Team Coordination Prompts -- team-level orchestration