Docs Document Pr

Skill: docs-document-pr

Description

Generates documentation from a GitHub pull request. Automatically gathers related issues, commits, and PR metadata, then writes a new docs page or appends a subsection to an existing page based on the content type.

Trigger: User says something like "document PR #123", "write docs for PR 456", "generate documentation from this PR", or "doc this PR".

---

Phase 1: Collect PR Data

Step 1a — Get PR metadata and commits

Use the gh CLI to fetch the PR number (the user provides this):

gh pr view  \
  --json title,body,labels,commits,closingIssuesReferences \
  --repo 

What to extract:

• PR title: The main feature/fix name
• PR body: Context, motivation, and any additional notes
• Labels: Look for feat, enhancement, new-module, schema-*, fix, etc.
• Commits: List of commit messages (useful for "What changed" section)
• Closing issues: Issue references the PR closes/fixes/resolves

Step 1b — Fetch linked issue details

For each issue referenced in the PR (via closingIssuesReferences or found via regex scan of PR body):

gh issue view  \
  --json title,body,labels \
  --repo 

What to extract:

• Issue title and body (motivation, requirements, discussion)
• Issue labels (helps understand priority, feature area)

Step 1c — Optional: Regex scan PR body

If the PR body mentions issues via keywords like:

• [Cc]loses?|[Ff]ixes?|[Rr]esolves?|[Rr]elates? to|see #

Extract issue numbers and fetch them. This catches manually-added issue references.

---

Phase 2: Decide — New Page or Subsection?

Create a NEW PAGE if:

• The PR introduces a new module, data type, or substantial feature (e.g., "Add XML support", "Add new codec type")
• No existing doc page closely covers the topic
• Labels include new-module, feat (not enhancement), or the PR title suggests something brand-new
• The PR is significant enough to warrant its own documentation space

Add a SUBSECTION if:

• The PR is an enhancement or bug fix to an existing feature
• An existing page in docs/reference/ or docs/guides/ already covers the parent topic
• Labels include enhancement, fix, or the PR touches an already-documented area
• You can logically fit the new content under an existing section

Heuristics

1. Match PR title against existing doc filenames:

• Scan docs/reference/ and docs/guides/ for .md files
• Extract the id field from each file's frontmatter
• If the PR topic matches an existing id, plan for a subsection

1. Check PR labels:

• schema-* labels → likely fits under docs/reference/schema.md (if it exists)
• feat + new name → likely a new page
• enhancement + existing area → likely a subsection
• fix → usually a subsection (documents the fix under an existing feature)

1. Example decisions:

• PR: "Add XML support" → New page: docs/reference/schema-xml.md
• PR: "Fix schema derivation" → Subsection in: docs/reference/schema.md → add under "Schema derivation"
• PR: "Add new module: Temporal" → New page: docs/reference/temporal.md

---

Phase 3: Write Documentation

Decision: Delegate to Specialized Skills

Do NOT write documentation directly. Instead, determine the doc type and use the appropriate ZIO project documentation skill:

Path 3a — NEW REFERENCE PAGE (API / Data Type)

When: PR introduces a new data type, module, codec, or technical feature

• Labels: feat, new-module, schema-*
• No existing parent doc to extend

Invoke: Use the docs-data-type-ref skill

User: "Create a reference page for this new Schema type from PR #1234"

The skill will:

• Gather the feature info from the PR (title, body, linked issues)
• Write a structured reference page with Overview, Usage, Examples, API Reference
• Follow ZIO project documentation conventions (style, code blocks, frontmatter)
• Return the file path

Path 3b — NEW HOW-TO GUIDE

When: PR introduces a workflow, pattern, or tutorial-style feature

• Labels: guide, enhancement, tutorial
• Teaches "how to accomplish X" with the new feature

Invoke: Use the docs-how-to-guide skill

User: "Create a how-to guide for the new temporal processing feature from PR #1234"

The skill will:

• Extract motivation and use-cases from PR and linked issues
• Write a step-by-step guide with concrete examples
• Follow ZIO project style and code block conventions
• Return the file path

Path 3c — ADD SUBSECTION to existing page

When: PR enhances an existing feature or fixes a documented area

• Labels: enhancement, fix
• Existing doc page covers the parent topic

Manual process:

1. Read the existing page at docs/reference/.md or docs/guides/.md
2. Extract PR context (issues, motivation, commits)
3. Append a new section using this structure:

```markdown ##

### Changes in this PR

### Example

\\\`scala

\\\`

### API Reference

```

1. Follow docs-writing-style for prose (refer to the skill for rules)
2. Follow docs-mdoc-conventions for code block syntax (refer to the skill for modifiers and admonitions)

Guidelines Across All Paths

1. Source content from the PR:

• PR title → doc title
• PR body + linked issue bodies → motivation, use-cases, context
• Commit messages → what changed (summarize key commits)
• Labels → doc type and categorization

1. Integrate with existing skills:

• Consult docs-writing-style for prose rules and tone
• Consult docs-mdoc-conventions for code block modifiers (:mdoc markers) and Docusaurus admonitions (:::note, :::warning)
• These skills provide shared guidelines used across all ZIO project docs

1. File naming and frontmatter:

• Use kebab-case for file names and id fields
• Always include frontmatter: id, title, optional sidebar_label
• Example:

``markdown --- id: schema-xml title: "XML Schema Support" sidebar_label: "XML" --- ``

---

Phase 4: Integrate with Docs Site

For new reference or how-to pages:

After the docs-data-type-ref or docs-how-to-guide skill returns the file path, use docs-integrate to finalize:

User: "Integrate the new schema-xml docs page"

The skill will:

• Check that frontmatter (id, title) is correct
• Verify the page exists at the correct path
• Update docs/sidebars.js in the appropriate category
• Confirm the sidebar entry is in alphabetical or logical position
• Provide verification steps

Manual backup: If you need to update the sidebar yourself:

1. Open docs/sidebars.js
2. Find the appropriate category (e.g., "Reference", "Guides")
3. Insert the id in correct alphabetical or logical position
4. Example:

``javascript { type: 'category', label: 'Reference', items: [ 'schema', 'schema-xml', //

• Linked issues: #123, #456, ... or "None found"
• Commits included: `` commits
• Key labels: ``

1. Decision made:

• "Created new page: docs/reference/schema-xml.md"
• or "Added subsection to: docs/reference/schema.md"

1. File(s) written:

• Path(s) to the created or modified file(s)
• Sidebar changes (if any)

1. Next steps (optional):

• "You can now review the generated docs and make refinements."
• "Consider adding code examples if the PR includes complex changes."

---

Phase 6: Verify Lint (If Examples Created)

If documentation involved creating or modifying .scala example files in schema-examples/, stage them in git first, then verify that all Scala code passes the CI formatting gate before reporting completion:

git add schema-examples/src/main/scala/**/*.scala
sbt fmtChanged

If any files were reformatted, commit the changes:

git add -A
git commit -m "docs(): apply scalafmt to examples"

Then verify the CI lint gate locally:

sbt check

Success criterion: zero formatting violations reported.

If no .scala files were created or modified, skip this phase.

---

Implementation Checklist

When you invoke this skill:

• [ ] Phase 1: Use gh pr view to fetch PR metadata and commits
• [ ] Phase 1: Use gh issue view for each linked issue (max ~5 issues per PR is typical)
• [ ] Phase 2: Check existing docs in docs/reference/ and docs/guides/ to decide new page vs. subsection
• [ ] Phase 2: Use PR labels and title as tiebreakers
• [ ] Phase 3a: If new reference/API page → invoke docs-data-type-ref skill with PR context
• [ ] Phase 3b: If new how-to guide → invoke docs-how-to-guide skill with PR context
• [ ] Phase 3c: If subsection → manually edit existing page, consult docs-writing-style and docs-mdoc-conventions skills
• [ ] Phase 4: If new page → invoke docs-integrate skill to update sidebar
• [ ] Phase 5: Report findings and file paths to user
• [ ] Phase 6: If .scala examples were created, run sbt fmt and sbt check to verify lint compliance

---

Example Invocations

For worked examples covering the common PR shapes (new reference page, new how-to guide, subsection addition, behaviour-change bugfix, and ambiguous PRs), load [references/example-invocations.md](references/example-invocations.md). Use it when you've identified the PR's shape in Phase 2 and want to confirm the workflow, or when a PR doesn't fit one of the obvious patterns.

---

Notes

• Auto-detect repo: Use git remote -v to find the GitHub repo URL if needed
• PR numbers: Assume user provides #123 format; extract the number
• No commits/issues: If a PR has no linked issues, use only PR title and body
• Ambiguous cases: If unsure whether to create a new page or subsection, default to a new page (easier to reorganize later) or ask the user

---

Final Verification

Before reporting back to the user, walk through every item in the sibling [CHECKLIST.md](CHECKLIST.md). It covers PR analysis, doc-type routing, per-doc quality (delegated), integration, and reporting.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zio
• Source: zio/zio-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.