Skip to content

Commit c11a3b7

Browse files
max-cxmax-cx
committed
add pdf-sg-review skill
1 parent c33ca22 commit c11a3b7

3 files changed

Lines changed: 284 additions & 0 deletions

File tree

‎.claude/skills/pdf-sg-review‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../plugins/docs-tools/skills/pdf-sg-review

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,9 @@ docs/plugins.md
2222
docs/plugins/
2323
docs/install/
2424
docs/superpowers/
25+
26+
# for plugins/docs-tools/skills/pdf-sg-review/SKILL.md
27+
plugins/docs-tools/skills/pdf-sg-review/style-guides/
28+
plugins/docs-tools/skills/pdf-sg-review/chunks/
29+
plugins/docs-tools/skills/pdf-sg-review/temp/
30+
plugins/docs-tools/skills/pdf-sg-review/reports/

‎plugins/docs-tools/skills/pdf-sg-review/SKILL.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
---
2+
context: none
3+
name: pdf-sg-review
4+
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.
5+
---
6+
7+
<!--
8+
You can use this skill with the following arguments:
9+
10+
- /pdf-sg-review https://github.com/org/repo/pull/123 - review a PR by URL
11+
- /pdf-sg-review #123 or /pdf-sg-review 123 - review a PR by number
12+
- /pdf-sg-review HEAD~1 - review a commit
13+
- /pdf-sg-review path/to/file.adoc - review a file
14+
- /pdf-sg-review - review the latest commit (default)
15+
-->
16+
17+
# Parallel PDF Style Review Workflow
18+
19+
This skill performs a parallelized PDF style review where multiple agents process chunk files concurrently.
20+
21+
## Content to Review
22+
23+
$ARGUMENTS
24+
25+
Interpret the argument as follows:
26+
- If it's a GitHub PR URL (e.g., `https://github.com/org/repo/pull/123`): use `gh pr diff <number>` to get the diff
27+
- If it's a PR number (e.g., `#123` or `123`): use `gh pr diff <number>` to get the diff
28+
- If it's a commit reference (e.g., `HEAD`, `HEAD~1`, `abc123`): review that commit's diff
29+
- If it's a commit range (e.g., `HEAD~3..HEAD`): review the diff for that range
30+
- If it's a file path (e.g., `docs/guide.adoc`): review that file's content
31+
- If it's a glob pattern (e.g., `modules/**/*.adoc`): review all matching files
32+
- If empty or not provided: review the latest commit (HEAD)
33+
34+
## Overview
35+
36+
Instead of sequentially reading all style guide chunk files and analyzing content against each, this workflow:
37+
1. Checks if chunk files exist, and if not, guides the user through PDF setup
38+
2. Lists all chunk files in the plugins/docs-tools/skills/pdf-sg-review/chunks/ directory
39+
3. Spawns multiple parallel agents (one per chunk)
40+
4. Each agent analyzes the commit content against its assigned chunk's rules
41+
5. Each agent writes findings to a separate temporary file
42+
6. A final merge step combines all findings into the review report
43+
44+
## Instructions
45+
46+
### Phase 0: Verify Chunks Exist
47+
48+
Before starting the review, check if the chunks directory exists and contains files:
49+
50+
1. Run the following command to check for chunk files:
51+
```bash
52+
ls ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/chunks/ 2>/dev/null | head -1
53+
```
54+
55+
2. **If chunks exist** (command returns output): Proceed to Phase 1.
56+
57+
3. **If chunks are missing** (command returns nothing or errors):
58+
59+
a. Inform the user:
60+
```
61+
No PDF style guide chunks found. I need to set up your style guides first.
62+
```
63+
64+
b. Check if `pdftotext` is installed:
65+
```bash
66+
which pdftotext
67+
```
68+
If not installed, tell the user:
69+
```
70+
The pdftotext command is required but not installed.
71+
Please install it with: sudo dnf install poppler-utils (Fedora)
72+
```
73+
Then STOP and wait for the user to install it.
74+
75+
c. Create the style-guides directory and get the full absolute path:
76+
```bash
77+
mkdir -p ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/style-guides && realpath ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/style-guides/
78+
```
79+
80+
CRITICAL: You MUST display the path to the user in this EXACT format (copy the path from the realpath command output):
81+
```
82+
Open your file manager and copy your PDF style guides to the following directory:
83+
<PASTE_THE_FULL_PATH_FROM_REALPATH_COMMAND_HERE>
84+
85+
...
86+
```
87+
88+
IMPORTANT: Replace <PASTE_THE_FULL_PATH_FROM_REALPATH_COMMAND_HERE> with the actual path returned by realpath. Do NOT use ~ or any abbreviation. The path must start with /home/ or similar absolute path.
89+
90+
Then use AskUserQuestion tool with options: ["Done - I uploaded the PDF(s)", "Skip - proceed without PDF review"]
91+
92+
d. If user chose to skip, inform them that PDF review cannot proceed without chunks and end the review.
93+
94+
e. If user uploaded PDFs, process them:
95+
```bash
96+
mkdir -p ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/chunks
97+
```
98+
99+
For each PDF file found in the style-guides directory:
100+
```bash
101+
cd ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/style-guides && for pdf in *.pdf; do
102+
if [[ -f "$pdf" ]]; then
103+
basename="${pdf%.pdf}"
104+
echo "Processing $pdf..."
105+
pdftotext -layout "./$pdf" "./${basename}.txt"
106+
split -l 1000 -d -a 3 -e "./${basename}.txt" "../chunks/${basename}_"
107+
echo "Created chunks for $pdf"
108+
fi
109+
done
110+
```
111+
112+
f. Verify chunks were created:
113+
```bash
114+
ls ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/chunks/ | wc -l
115+
```
116+
If count is 0, inform the user that no PDFs were found or processing failed, and STOP.
117+
118+
g. Inform the user of success and proceed to Phase 1.
119+
120+
### Phase 1: Setup
121+
122+
1. Create the reports directory if it doesn't exist, then create the main review report file:
123+
```bash
124+
mkdir -p ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/reports
125+
```
126+
127+
Save the report as `~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/reports/review-<YYYY-MM-DD-hh:mm:ss>.md` with the header:
128+
```
129+
AI review report
130+
(Do not use preview to read this report unless your previews are set to a monospace font.)
131+
132+
**User request:** <user's request>
133+
134+
**Commit:** <commit hash>
135+
**Subject:** <commit subject>
136+
```
137+
138+
2. List all chunk files in `plugins/docs-tools/skills/pdf-sg-review/chunks/` directory and its subdirectories:
139+
```
140+
ls ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/chunks/
141+
```
142+
Store the list of chunk filenames for spawning agents.
143+
144+
3. Create the temporary directory if it doesn't exist:
145+
```bash
146+
mkdir -p ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/temp
147+
```
148+
149+
4. Retrieve the commit diff content and save it to a temporary file:
150+
```
151+
~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/temp/commit-diff.txt
152+
```
153+
154+
### Phase 2: Parallel Analysis
155+
156+
Launch parallel agents using the Task tool - one agent per chunk file found in Phase 1. Each agent receives:
157+
158+
**Agent Prompt Template:**
159+
```
160+
You are analyzing documentation content for style guide violations.
161+
162+
1. Read the chunk file: ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/chunks/<CHUNK_FILENAME>
163+
2. Read the commit diff: ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/temp/commit-diff.txt
164+
165+
3. Analyze every sentence in the commit diff against ALL rules in your assigned chunk.
166+
167+
4. Return your findings in your response (do NOT write to any files). Use this format:
168+
169+
CHUNK: <CHUNK_FILENAME>
170+
VIOLATIONS_FOUND: <number>
171+
172+
If violations found, list each one:
173+
---VIOLATION---
174+
FILE: <filename>
175+
CURRENT: <sentence where violation appears>
176+
SUGGESTED: <corrected sentence>
177+
RULE: <first sentence of the style rule>
178+
TOCPATH: <Style Guide Name> > <Section> > <Subsection>
179+
---END---
180+
181+
If no violations found, return:
182+
CHUNK: <CHUNK_FILENAME>
183+
VIOLATIONS_FOUND: 0
184+
NO_VIOLATIONS_REASON: <brief explanation of what rules were checked>
185+
```
186+
187+
**Parallel Execution:**
188+
- Use a single message with multiple Task tool invocations
189+
- Set subagent_type to "general-purpose"
190+
- Each agent handles exactly one chunk file
191+
- Agents return findings in their response (no file writes needed)
192+
- No permission issues since agents don't write files
193+
194+
### Phase 3: Merge Results
195+
196+
After all parallel agents complete:
197+
198+
1. Parse each agent's response to extract violations:
199+
- Look for the `---VIOLATION---` markers in agent results
200+
- Extract FILE, CURRENT, SUGGESTED, RULE, TOCPATH fields
201+
- Skip agents with `VIOLATIONS_FOUND: 0`
202+
203+
2. Combine findings into the main review report file:
204+
- Renumber all issues sequentially (Issue 1, Issue 2, etc.)
205+
- **CRITICAL:** Convert each violation to the exact format specified in the "Review Report Format" section below - do NOT use any other format
206+
- Deduplicate issues that flag the same sentence
207+
208+
3. Append "End of report" to the review report file
209+
210+
4. Clean up temporary files:
211+
```bash
212+
rm -rf ~/redhat-docs-agent-tools/plugins/docs-tools/skills/pdf-sg-review/temp
213+
```
214+
215+
## Review Report Format
216+
217+
Start every response with a line "AI review report".
218+
On the next line after "AI review report", add a line "(Do not use preview to read this report unless your previews are set to a monospace font.)
219+
220+
End every response with a line "End of report".
221+
222+
Each of the other attached sources contains a plurality of rules.
223+
224+
You must review every sentence of the entered text separately, sentence by sentence for violations of all rules (issues) in the sentence.
225+
226+
Number the issues in the order in which you add them.
227+
228+
If you detect only one violation in a sentence, then use the following format to document the violation:
229+
230+
* **Issue 1**
231+
* **File:** <filename from the last line of the entered text that contains `--- a`> (skip this line if there are no instances of `--- a` in the text)
232+
* **Current sentence:** `<sentence where the violation appears>` (enclose this sentence with opening and closing `)
233+
* **Suggested change:** `<sentence of violation updated to resolve the violation>` (enclose this sentence with opening and closing `)(do not emphasize the changes)
234+
* **Style rule:** <copy the first sentence of the style rule>
235+
* **TOC path:** *<Source Title>* > *<CHAPTER>* > *<Section>* > *<Subsection>* (include all TOC levels)
236+
237+
(start the next list item, which is for the next sentence, after a blank line)
238+
239+
If you detect multiple violations in a sentence, then use the following format to document the violations for that particular sentence:
240+
241+
* **Issue 2**
242+
* **File:** <filename from the last line of the entered text that contains `--- a`> (skip this line if there are no instances of `--- a` in the text)
243+
* **Current sentence:** `<sentence where the violation appears>` (enclose this sentence with opening and closing `)
244+
* **Suggested change:** `<sentence of violation updated to resolve the violation>` (enclose this sentence with opening and closing `)(do not emphasize the changes)
245+
* **⚠ WARNING!** Sentence with multiple issues! Evaluate suggestions one by one!
246+
* **Style rule:** <copy the first sentence of the style rule>
247+
* **TOC path:** *<Source Title>* > *<CHAPTER>* > *<Section>* > *<Subsection>* (include all TOC levels)
248+
* **Issue 3**
249+
* **Current sentence:** `<sentence where the violation appears>` (enclose this sentence with opening and closing `)
250+
* **Suggested change:** `<sentence of violation updated to resolve the violation>` (enclose this sentence with opening and closing `)(do not emphasize the changes)
251+
* **⚠ WARNING!** Sentence with multiple issues! Evaluate suggestions one by one!
252+
* **Style rule:** <copy_the_first_sentence_of_the_style_rule>
253+
* **TOC path:** *<Source Title>* > *<CHAPTER>* > *<Section>* > *<Subsection>* (include all TOC levels)
254+
255+
(start the next list item, which is for the next sentence, after a blank line)
256+
257+
## Phase 4: Interactive Issue Resolution
258+
259+
After completing all review tasks and generating the report:
260+
261+
1. **Check if issues were found**: If at least one issue was detected during the review, proceed to step 2. If no issues were found, skip this phase.
262+
263+
2. **Prompt the user**: Ask the user whether they want to review and fix the issues one by one using the AskUserQuestion tool with options:
264+
- "Yes - go through issues one by one"
265+
- "No - keep the report as-is"
266+
267+
3. **If the user chooses to go through issues**: For each issue in the report, present the issue details in the Review Report Format and offer three choices using the AskUserQuestion tool:
268+
- **Apply**: Apply the suggested change to the source file
269+
- **Skip**: Leave the original text unchanged and move to the next issue
270+
- **Modify**: Allow the user to provide a custom fix (different from the suggested change)
271+
272+
4. **Process user choices**:
273+
- **Apply**: Use the Edit tool to replace the current sentence with the suggested change in the source file
274+
- **Skip**: Take no action and proceed to the next issue
275+
- **Modify**: Wait for the user to provide their custom text, then use the Edit tool to apply their modification
276+
277+
5. **Continue until all issues are processed** or the user requests to stop.

0 commit comments

Comments
 (0)