home / skills / phrazzld / claude-config / log-doc-issues

log-doc-issues skill

safe

/skills/log-doc-issues

This skill audits documentation with /check-docs and creates prioritized GitHub issues for findings, avoiding duplicates.

npx playbooks add skill phrazzld/claude-config --skill log-doc-issues

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.6 KB

---
name: log-doc-issues
description: |
  Run /check-docs, then create GitHub issues for all findings.
  Issues are created with priority labels and structured format.
  Use /fix-docs instead if you want to fix issues immediately.
effort: medium
---

# /log-doc-issues

Run documentation audit and create GitHub issues for all findings.

## What This Does

1. Invoke `/check-docs` to audit documentation
2. Parse findings by priority (P0-P3)
3. Check existing issues to avoid duplicates
4. Create GitHub issues for each finding

**This is an issue-creator.** It creates work items, not fixes. Use `/fix-docs` to fix issues.

## Process

### 1. Run Primitive

Invoke `/check-docs` skill to get structured findings.

### 2. Check Existing Issues

```bash
gh issue list --state open --label "domain/docs" --limit 50
```

### 3. Create Issues

For each finding:

```bash
gh issue create \
  --title "[P1] README missing Installation section" \
  --body "$(cat <<'EOF'
## Problem
README.md exists but lacks Installation section. New developers cannot set up the project.

## Impact
- Contributor onboarding blocked
- Time wasted figuring out setup
- Potential contributors give up

## Location
`README.md`

## Suggested Fix
Run `/fix-docs` or add manually:
- Prerequisites (Node version, etc.)
- Package manager commands
- Environment setup steps

---
Created by `/log-doc-issues`
EOF
)" \
  --label "priority/p1,domain/docs,type/chore"
```

### 4. Issue Format

**Title:** `[P{0-3}] Documentation gap description`

**Labels:**
- `priority/p0` | `priority/p1` | `priority/p2` | `priority/p3`
- `domain/docs`
- `type/chore`

**Body:**
```markdown
## Problem
What documentation is missing or broken

## Impact
Who is affected (new devs, users, contributors)

## Location
File path or expected file location

## Suggested Fix
Skill to run or manual action

---
Created by `/log-doc-issues`
```

## Priority Mapping

| Gap | Priority |
|-----|----------|
| Missing README.md | P0 |
| Missing .env.example (with env vars used) | P0 |
| README missing key sections | P1 |
| Undocumented env vars | P1 |
| Missing architecture docs | P1 |
| Stale documentation (90+ days) | P2 |
| Missing CONTRIBUTING.md | P2 |
| Missing ADR directory | P2 |
| Broken links | P2 |
| Polish improvements | P3 |

## Output

After running:
```
Documentation Issues Created:
- P0: 0
- P1: 3 (README sections, env vars)
- P2: 2 (stale docs, ADRs)
- P3: 1 (link checking)

Total: 6 issues created
View: gh issue list --label domain/docs
```

## Related

- `/check-docs` - The primitive (audit only)
- `/fix-docs` - Fix documentation gaps
- `/documentation` - Full documentation workflow
- `/groom` - Full backlog grooming

Overview

This skill runs a documentation audit and creates GitHub issues for every finding. It groups findings by priority (P0–P3), avoids duplicate issues, and opens well-structured issues with labels and a suggested fix. Use this to convert audit results into actionable work items; use /fix-docs when you want the tool to apply fixes instead of creating issues.

How this skill works

The skill invokes /check-docs to produce structured findings, parses each finding into a priority bucket, and queries open issues to avoid duplicates. For each unique finding it builds a templated issue (Problem, Impact, Location, Suggested Fix), assigns priority and domain labels, and creates the issue via gh issue create. It reports counts by priority after execution.

When to use it

After running or scheduling a docs audit with /check-docs
When you want maintainers to triage and act on documentation problems
Before a release or onboarding drive to capture gaps as work items
When you want an auditable backlog of documentation work instead of automated fixes
If you need standardized issue descriptions and priority labels

Best practices

Run /check-docs first so findings are accurate and structured
Limit duplicate noise by ensuring open issues are checked before creation
Review priority mapping and adjust labels if your team uses different SLAs
Include clear Suggested Fix items so contributors can pick tasks easily
Run on a schedule (weekly or monthly) for ongoing documentation hygiene

Example use cases

Create issues for missing README sections and undocumented environment variables after an audit
Capture stale docs and missing ADRs as backlog items for a documentation sprint
Generate prioritized chores before onboarding new contributors to improve setup docs
Automate issue creation for link rot, broken links, and minor polish tasks discovered by the audit
Run in CI to surface documentation gaps in a dedicated GitHub label for triage

FAQ

Will this skill modify repository files?

No. It only creates GitHub issues. Use /fix-docs if you want automated modifications.

How are priorities determined?

Priorities map to common gaps: missing README or .env.example are P0; missing sections or env var docs are P1; stale docs and missing ADRs are P2; polish items are P3.

How does it avoid duplicates?

It lists recent open issues with the domain/docs label and compares titles or locations before creating new issues.