diff --git a/.claude/skills/pdf-sg-review b/.claude/skills/pdf-sg-review new file mode 120000 index 00000000..0622dad9 --- /dev/null +++ b/.claude/skills/pdf-sg-review @@ -0,0 +1 @@ +../../plugins/docs-tools/skills/pdf-sg-review \ No newline at end of file diff --git a/.gitignore b/.gitignore index c43ebe4a..1ff0e1ad 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,9 @@ docs/plugins.md docs/plugins/ docs/install/ docs/superpowers/ + +# for plugins/docs-tools/skills/pdf-sg-review/SKILL.md +plugins/docs-tools/skills/pdf-sg-review/style-guides/ +plugins/docs-tools/skills/pdf-sg-review/chunks/ +plugins/docs-tools/skills/pdf-sg-review/temp/ +plugins/docs-tools/skills/pdf-sg-review/reports/ diff --git a/plugins/docs-tools/skills/pdf-sg-review/SKILL.md b/plugins/docs-tools/skills/pdf-sg-review/SKILL.md new file mode 100644 index 00000000..a198b3ae --- /dev/null +++ b/plugins/docs-tools/skills/pdf-sg-review/SKILL.md @@ -0,0 +1,274 @@ +--- +context: none +name: pdf-sg-review +description: Parallel PDF style review workflow using PDF style guide chunks. Reviews PRs, commits, or files against PDF style guide rules. Use with arguments like PR URLs (#123), commit refs (HEAD~1), or file paths. Spawns parallel agents to analyze content against style guide chunks for faster review. +--- + + + +# Parallel PDF Style Review Workflow + +This skill performs a parallelized PDF style review where multiple agents process chunk files concurrently. + +## Content to Review + +$ARGUMENTS + +Interpret the argument as follows: +- If it's a GitHub PR URL (e.g., `https://github.com/org/repo/pull/123`): use `gh pr diff ` to get the diff +- If it's a PR number (e.g., `#123` or `123`): use `gh pr diff ` to get the diff +- If it's a commit reference (e.g., `HEAD`, `HEAD~1`, `abc123`): review that commit's diff +- If it's a commit range (e.g., `HEAD~3..HEAD`): review the diff for that range +- If it's a file path (e.g., `docs/guide.adoc`): review that file's content +- If it's a glob pattern (e.g., `modules/**/*.adoc`): review all matching files +- If empty or not provided: review the latest commit (HEAD) + +## Overview + +Instead of sequentially reading all style guide chunk files and analyzing content against each, this workflow: +1. Checks if chunk files exist, and if not, guides the user through PDF setup +2. Lists all chunk files in the plugins/docs-tools/skills/pdf-sg-review/chunks/ directory +3. Spawns multiple parallel agents (one per chunk) +4. Each agent analyzes the commit content against its assigned chunk's rules +5. Each agent writes findings to a separate temporary file +6. A final merge step combines all findings into the review report + +## Instructions + +### Phase 0: Verify Chunks Exist + +Before starting the review, check if the chunks directory exists and contains files: + +1. Run the following command to check for chunk files: + ```bash + ls ${CLAUDE_SKILL_DIR}/chunks/ 2>/dev/null | head -1 + ``` + +2. **If chunks exist** (command returns output): Proceed to Phase 1. + +3. **If chunks are missing** (command returns nothing or errors): + + a. Inform the user: + ```text + No PDF style guide chunks found. I need to set up your style guides first. + ``` + + b. Check if `pdftotext` is installed: + ```bash + which pdftotext + ``` + If not installed, tell the user: + ```text + The pdftotext command is required but not installed. + Please install it with: sudo dnf install poppler-utils (Fedora) + ``` + Then STOP and wait for the user to install it. + + c. Create the style-guides directory and get the full absolute path: + ```bash + mkdir -p ${CLAUDE_SKILL_DIR}/style-guides && realpath ${CLAUDE_SKILL_DIR}/style-guides/ + ``` + + CRITICAL: You MUST display the path to the user in this EXACT format (copy the path from the realpath command output): + ```text + Open your file manager and copy your PDF style guides to the following directory: + + + ... + ``` + + IMPORTANT: Replace with the actual path returned by realpath. Do NOT use ~ or any abbreviation. The path must start with /home/ or similar absolute path. + + Then use AskUserQuestion tool with options: ["Done - I uploaded the PDF(s)", "Skip - proceed without PDF review"] + + d. If user chose to skip, inform them that PDF review cannot proceed without chunks and end the review. + + e. If user uploaded PDFs, process them: + ```bash + mkdir -p ${CLAUDE_SKILL_DIR}/chunks + ``` + + For each PDF file found in the style-guides directory: + ```bash + cd ${CLAUDE_SKILL_DIR}/style-guides && for pdf in *.pdf; do + if [[ -f "$pdf" ]]; then + basename="${pdf%.pdf}" + echo "Processing $pdf..." + pdftotext -layout "./$pdf" "./${basename}.txt" + split -l 1000 -d -a 3 -e "./${basename}.txt" "../chunks/${basename}_" + echo "Created chunks for $pdf" + fi + done + ``` + + f. Verify chunks were created: + ```bash + ls ${CLAUDE_SKILL_DIR}/chunks/ | wc -l + ``` + If count is 0, inform the user that no PDFs were found or processing failed, and STOP. + + g. Inform the user of success and proceed to Phase 1. + +### Phase 1: Setup + +1. Create the reports directory if it doesn't exist, then create the main review report file: + ```bash + mkdir -p ${CLAUDE_SKILL_DIR}/reports + ``` + + Save the report as `${CLAUDE_SKILL_DIR}/reports/review-.md` with the header: + ```text + AI review report + (Do not use preview to read this report unless your previews are set to a monospace font.) + + **User request:** + + **Commit:** + **Subject:** + ``` + +2. List all chunk files in `plugins/docs-tools/skills/pdf-sg-review/chunks/` directory: + ```bash + ls ${CLAUDE_SKILL_DIR}/chunks/ + ``` + Store the list of chunk filenames for spawning agents. + +3. Create the temporary directory if it doesn't exist: + ```bash + mkdir -p ${CLAUDE_SKILL_DIR}/temp + ``` + +4. Retrieve the commit diff content and save it to a temporary file with the following path and file name: `${CLAUDE_SKILL_DIR}/temp/commit-diff.txt` + +### Phase 2: Parallel Analysis + +Launch parallel agents using the Task tool - one agent per chunk file found in Phase 1. Each agent receives: + +**Agent Prompt Template:** +```text +You are analyzing documentation content for style guide violations. + +1. Read the chunk file: ${CLAUDE_SKILL_DIR}/chunks/ +2. Read the commit diff: ${CLAUDE_SKILL_DIR}/temp/commit-diff.txt + +3. Analyze every sentence in the commit diff against ALL rules in your assigned chunk. + +4. Return your findings in your response (do NOT write to any files). Use this format: + + CHUNK: + VIOLATIONS_FOUND: + + If violations found, list each one: + ---VIOLATION--- + FILE: + CURRENT: + SUGGESTED: + RULE: + TOCPATH: