Skip to content

Commit ead5a4b

Browse files
PureWeenkubaflo
PureWeen
authored and
kubaflo
committed
Post pr comment skill
1 parent 43d86be commit ead5a4b

15 files changed

Lines changed: 2152 additions & 393 deletions

File tree

‎.github/agents/learn-from-pr.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
name: learn-from-pr
3+
description: Analyzes completed PRs for lessons learned, then applies improvements to instruction files, skills, and documentation.
4+
---
5+
6+
# Learn From PR Agent
7+
8+
Extracts lessons from completed PRs and **applies** improvements to the repository.
9+
10+
## When to Invoke
11+
12+
- "Learn from PR #XXXXX and apply improvements"
13+
- "Update the repo based on what we learned from PR #XXXXX"
14+
- After any PR with agent involvement (failed, slow success, or quick success)
15+
16+
## When NOT to Invoke
17+
18+
- For analysis only without applying changes → use `/learn-from-pr` skill
19+
- Before PR is finalized
20+
- For trivial PRs with no learning value
21+
22+
---
23+
24+
## Workflow
25+
26+
### Phase 1: Analysis
27+
28+
Run the `/learn-from-pr` skill workflow (Steps 1-6) to generate recommendations.
29+
30+
The skill covers three outcome types:
31+
- **Agent failed** - What was missing that caused wrong attempts
32+
- **Agent succeeded slowly** - What would have gotten to solution faster
33+
- **Agent succeeded quickly** - What patterns to reinforce
34+
35+
### Phase 2: Apply Changes
36+
37+
For each **High or Medium priority** recommendation:
38+
39+
| Category | Action |
40+
|----------|--------|
41+
| Instruction file | Edit existing or create new `.github/instructions/*.instructions.md` |
42+
| Skill enhancement | Edit `.github/skills/*/SKILL.md` |
43+
| Architecture doc | Create/edit `.github/architecture/*.md` |
44+
| Code comment | Add comment to source file (don't modify behavior) |
45+
46+
**Before each edit:**
47+
- Read the target file first
48+
- Check for existing similar content (don't duplicate)
49+
- Match the existing style/format
50+
- Find the appropriate section
51+
52+
**Skip applying if:**
53+
- Content already exists
54+
- Recommendation is too vague
55+
- Would require major restructuring
56+
57+
### Phase 2.5: Verify Changes
58+
59+
After applying changes:
60+
61+
1. Run `git diff` to review all edits
62+
2. Verify no syntax errors in modified files (valid markdown)
63+
3. Confirm style matches existing content
64+
4. If issues found, fix or revert before reporting
65+
66+
### Phase 3: Report
67+
68+
Present a summary:
69+
70+
```markdown
71+
## Changes Applied
72+
73+
| File | Change |
74+
|------|--------|
75+
| [path] | [what was added/modified] |
76+
77+
## Not Applied
78+
79+
| Recommendation | Reason |
80+
|----------------|--------|
81+
| [rec] | [why skipped] |
82+
```
83+
84+
---
85+
86+
## Error Handling
87+
88+
| Situation | Action |
89+
|-----------|--------|
90+
| PR not found | Ask user to verify PR number |
91+
| No session markdown | Proceed with PR diff analysis only |
92+
| Target file doesn't exist | Create if instruction/architecture doc, skip if code |
93+
| Duplicate content exists | Skip, note in report |
94+
| Unclear where to add | Ask user for guidance |
95+
96+
## Constraints
97+
98+
- **Only apply High/Medium priority** - Report Low priority without applying
99+
- **Don't duplicate** - Check existing content first
100+
- **Match style** - Read file before editing
101+
- **Code comments only** - Never modify code behavior
102+
- **No linter implementation** - File issue instead of building analyzers
103+
104+
---
105+
106+
## Difference from Skill
107+
108+
| Aspect | `/learn-from-pr` Skill | This Agent |
109+
|--------|------------------------|------------|
110+
| Output | Recommendations to discuss | Applied changes |
111+
| Mode | Analysis only | Autonomous |
112+
| Use when | Want to review without applying | CI automation |

‎.github/agents/pr.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,23 @@ After Gate passes, read `.github/agents/pr/post-gate.md` for **Phases 4-5**.
3939
└─────────────────────────────────────────┘ └─────────────────────────────────────────────┘
4040
```
4141

42+
---
43+
44+
## Phase Completion Protocol (CRITICAL)
45+
46+
**Before changing ANY phase status to ✅ COMPLETE:**
47+
48+
1. **Read the state file section** for the phase you're completing
49+
2. **Find ALL ⏳ PENDING and [PENDING] fields** in that section
50+
3. **Fill in every field** with actual content
51+
4. **Verify no pending markers remain** in your section
52+
5. **Commit the state file** with complete content
53+
6. **Then change status** to ✅ COMPLETE
54+
55+
**Rule:** Status ✅ means "documentation complete", not "I finished thinking about it"
56+
57+
---
58+
4259
### 🚨 CRITICAL: Phase 4 Always Uses `try-fix` Skill
4360

4461
**Even when a PR already has a fix**, Phase 4 requires running the `try-fix` skill to:
@@ -320,12 +337,31 @@ The test result will be updated to `✅ PASS (Gate)` after Gate passes.
320337

321338
### Step 5: Complete Pre-Flight
322339

340+
**🚨 MANDATORY: Update state file AND post comment**
341+
323342
**Update state file** - Change Pre-Flight status and populate with gathered context:
324343
1. Change Pre-Flight status from `▶️ IN PROGRESS` to `✅ COMPLETE`
325344
2. Fill in issue summary, platforms affected, regression info
326345
3. Add edge cases and any disagreements (if PR exists)
327346
4. Change 🧪 Tests status to `▶️ IN PROGRESS`
328347

348+
**Before marking ✅ COMPLETE, verify state file contains:**
349+
- [ ] Issue summary filled (not [PENDING])
350+
- [ ] Platform checkboxes marked
351+
- [ ] Files Changed table populated (if PR exists)
352+
- [ ] PR Discussion Summary documented (if PR exists)
353+
- [ ] All [PENDING] placeholders replaced
354+
- [ ] State file committed
355+
356+
**Post completion comment (if PR exists) - MANDATORY, DO NOT SKIP:**
357+
```bash
358+
cat .github/agent-pr-session/pr-XXXXX.md | pwsh .github/skills/pr-comment/scripts/post-pr-comment.ps1 -PRNumber XXXXX
359+
```
360+
361+
**⚠️ The script ALWAYS updates the ONE aggregated review comment with all phases. If the comment doesn't exist yet, it creates it.**
362+
363+
This posts a formatted comment to the PR notifying that Pre-Flight is complete with a summary of findings and next steps.
364+
329365
---
330366

331367
## 🧪 TESTS: Create/Verify Reproduction Tests (Phase 2)
@@ -378,13 +414,28 @@ The script auto-detects mode based on git diff. If only test files changed, it v
378414

379415
### Complete 🧪 Tests
380416

417+
**🚨 MANDATORY: Update state file AND post comment**
418+
381419
**Update state file**:
382420
1. Check off completed items in the checklist
383421
2. Fill in test file paths
384422
3. Note: "Tests verified to FAIL (bug reproduced)"
385423
4. Change 🧪 Tests status to `✅ COMPLETE`
386424
5. Change 🚦 Gate status to `▶️ IN PROGRESS`
387425

426+
**Before marking ✅ COMPLETE, verify state file contains:**
427+
- [ ] Test file paths documented
428+
- [ ] "Tests verified to FAIL" note added
429+
- [ ] Test category identified
430+
- [ ] State file committed
431+
432+
**Post completion comment (if PR exists) - MANDATORY, DO NOT SKIP:**
433+
```bash
434+
cat .github/agent-pr-session/pr-XXXXX.md | pwsh .github/skills/pr-comment/scripts/post-pr-comment.ps1 -PRNumber XXXXX
435+
```
436+
437+
**⚠️ The script ALWAYS updates the ONE aggregated review comment with all phases. If the comment doesn't exist yet, it creates it.**
438+
388439
---
389440

390441
## 🚦 GATE: Verify Tests Catch the Issue (Phase 3)
@@ -427,11 +478,26 @@ pwsh .github/skills/verify-tests-fail-without-fix/scripts/verify-tests-fail.ps1
427478

428479
### Complete 🚦 Gate
429480

481+
**🚨 MANDATORY: Update state file AND post comment**
482+
430483
**Update state file**:
431484
1. Fill in **Result**: `PASSED ✅`
432485
2. Change 🚦 Gate status to `✅ PASSED`
433486
3. Proceed to Phase 4
434487

488+
**Before marking ✅ PASSED, verify state file contains:**
489+
- [ ] Result shows PASSED ✅ or FAILED ❌
490+
- [ ] Test behavior documented
491+
- [ ] Platform tested noted
492+
- [ ] State file committed
493+
494+
**Post completion comment (if PR exists) - MANDATORY, DO NOT SKIP:**
495+
```bash
496+
cat .github/agent-pr-session/pr-XXXXX.md | pwsh .github/skills/pr-comment/scripts/post-pr-comment.ps1 -PRNumber XXXXX
497+
```
498+
499+
**⚠️ The script ALWAYS updates the ONE aggregated review comment with all phases. If the comment doesn't exist yet, it creates it.**
500+
435501
---
436502

437503
## ⛔ STOP HERE

‎.github/agents/pr/post-gate.md‎

Lines changed: 66 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,21 @@ If Gate is not passed, go back to `.github/agents/pr.md` and complete phases 1-3
1515

1616
---
1717

18+
## Phase Completion Protocol (CRITICAL)
19+
20+
**Before changing ANY phase status to ✅ COMPLETE:**
21+
22+
1. **Read the state file section** for the phase you're completing
23+
2. **Find ALL ⏳ PENDING and [PENDING] fields** in that section
24+
3. **Fill in every field** with actual content
25+
4. **Verify no pending markers remain** in your section
26+
5. **Commit the state file** with complete content
27+
6. **Then change status** to ✅ COMPLETE
28+
29+
**Rule:** Status ✅ means "documentation complete", not "I finished thinking about it"
30+
31+
---
32+
1833
## 🔧 FIX: Explore and Select Fix (Phase 4)
1934

2035
> **SCOPE**: Explore independent fix alternatives using `try-fix` skill, compare with PR's fix, select the best approach.
@@ -37,25 +52,38 @@ The purpose of Phase 4 is NOT to re-test the PR's fix, but to:
3752

3853
Invoke the `try-fix` skill repeatedly. The skill handles one fix attempt per invocation.
3954

55+
**IMPORTANT:** Always pass the `state_file` parameter so try-fix can record its results:
56+
```
57+
state_file: .github/agent-pr-session/pr-XXXXX.md
58+
```
59+
60+
try-fix will automatically append rows to the Fix Candidates table. You remain responsible for:
61+
- Setting "Exhausted" field when done
62+
- Setting "Selected Fix" field with reasoning
63+
- Updating phase status to ✅ COMPLETE
64+
4065
```
4166
┌─────────────────────────────────────────────────────────────┐
4267
│ Agent orchestration loop │
4368
├─────────────────────────────────────────────────────────────┤
4469
│ │
4570
│ attempts = 0 │
4671
│ max_attempts = 5 │
72+
│ state_file = ".github/agent-pr-session/pr-XXXXX.md" │
4773
│ │
4874
│ while (attempts < max_attempts): │
49-
│ result = invoke try-fix skill │
75+
│ result = invoke try-fix skill (with state_file) │
5076
│ attempts++ │
5177
│ │
5278
│ if result.exhausted: │
5379
│ break # try-fix has no more ideas │
5480
│ │
5581
│ # result.passed indicates if this attempt worked │
82+
│ # try-fix already recorded to state file │
5683
│ # Continue loop to explore more alternatives │
5784
│ │
5885
│ # After loop: compare all try-fix results vs PR's fix │
86+
│ # Update "Exhausted" and "Selected Fix" fields │
5987
│ │
6088
└─────────────────────────────────────────────────────────────┘
6189
```
@@ -73,8 +101,9 @@ Each `try-fix` invocation:
73101
3. Proposes ONE new independent fix idea
74102
4. Implements and tests it
75103
5. Records result (with failure analysis if it failed)
76-
6. Reverts all changes (restores PR's fix)
77-
7. Returns `{passed: bool, exhausted: bool}`
104+
6. **Updates state file** (appends row to Fix Candidates table if state_file provided)
105+
7. Reverts all changes (restores PR's fix)
106+
8. Returns `{passed: bool, exhausted: bool}`
78107

79108
See `.github/skills/try-fix/SKILL.md` for full details.
80109

@@ -127,13 +156,31 @@ Update the state file:
127156

128157
### Complete 🔧 Fix
129158

159+
**🚨 MANDATORY: Update state file AND post comment**
160+
130161
**Update state file**:
131162
1. Verify Fix Candidates table is complete with all attempts
132163
2. Verify failure analyses are documented for failed attempts
133164
3. Verify Selected Fix is documented with reasoning
134165
4. Change 🔧 Fix status to `✅ COMPLETE`
135166
5. Change 📋 Report status to `▶️ IN PROGRESS`
136167

168+
**Before marking ✅ COMPLETE, verify state file contains:**
169+
- [ ] Root Cause Analysis filled in (if applicable)
170+
- [ ] Fix Candidates table has numbered rows for each try-fix attempt
171+
- [ ] Each row has: approach, test result, files changed, notes
172+
- [ ] "Exhausted" field set (Yes/No)
173+
- [ ] "Selected Fix" populated with reasoning
174+
- [ ] No ⏳ PENDING markers remain in Fix section
175+
- [ ] State file committed
176+
177+
**Post completion comment (if PR exists) - MANDATORY, DO NOT SKIP:**
178+
```bash
179+
cat .github/agent-pr-session/pr-XXXXX.md | pwsh .github/skills/pr-comment/scripts/post-pr-comment.ps1 -PRNumber XXXXX
180+
```
181+
182+
**⚠️ The script ALWAYS updates the ONE aggregated review comment with all phases. If the comment doesn't exist yet, it creates it.**
183+
137184
---
138185

139186
## 📋 REPORT: Final Report (Phase 5)
@@ -228,11 +275,27 @@ Update all phase statuses to complete.
228275

229276
### Complete 📋 Report
230277

278+
**🚨 MANDATORY: Update state file AND post comment**
279+
231280
**Update state file**:
232281
1. Change header status to final recommendation
233282
2. Update all phases to `✅ COMPLETE` or `✅ PASSED`
234283
3. Present final result to user
235284

285+
**Before marking ✅ COMPLETE, verify state file contains:**
286+
- [ ] Final recommendation (APPROVE/REQUEST_CHANGES/COMMENT)
287+
- [ ] Summary of findings
288+
- [ ] Key technical insights documented
289+
- [ ] Overall status changed to final recommendation
290+
- [ ] State file committed
291+
292+
**Post completion comment (if PR exists) - MANDATORY, DO NOT SKIP:**
293+
```bash
294+
cat .github/agent-pr-session/pr-XXXXX.md | pwsh .github/skills/pr-comment/scripts/post-pr-comment.ps1 -PRNumber XXXXX
295+
```
296+
297+
**⚠️ The script ALWAYS updates the ONE aggregated review comment with all phases. If the comment doesn't exist yet, it creates it.**
298+
236299
---
237300

238301
## Common Mistakes in Post-Gate Phases

0 commit comments

Comments
 (0)