Learn
Purpose
Continuous improvement from delivery outcomes. Analyzes merged PRs to find where AI missed what human reviewers caught, identifies false positives, and synthesizes recurring patterns into context updates. The feedback loop that makes the framework smarter over time.
Trigger
- Command:
/ai-learn single <pr>|batch|apply
- Context: after PR merge (single), periodic review (batch), enough patterns accumulated (apply).
Modes
single -- Analyze one merged PR
Fetch PR data -- gh pr view <pr> --json body,reviews,comments,files,additions,deletions.
Collect AI findings -- read the AI-generated PR description, guard advisories, and verify results from the PR.
Collect human feedback -- extract all review comments, requested changes, and approval notes.
Cross-reference -- compare AI findings with human feedback:
| Category |
Description |
| AI miss |
Human reviewer found an issue AI did not flag |
| False positive |
AI flagged something human reviewer dismissed or overrode |
| AI hit |
AI flagged an issue human reviewer agreed with |
| Novel insight |
Human added context AI could not have known |
Record -- append learning entry to .ai-engineering/learnings/index.jsonl:
{"pr": 123, "date": "2026-03-19", "misses": 2, "false_positives": 1, "hits": 5, "patterns": ["missed-null-check", "over-flagged-naming"]}
batch -- Process unanalyzed PRs
- Find unanalyzed -- list merged PRs not yet in
index.jsonl.
- Process each -- run single-mode analysis for each.
- Summary -- report total misses, false positives, and emerging patterns.
apply -- Synthesize into context updates
- Load learnings -- read
.ai-engineering/learnings/index.jsonl.
- Find recurring patterns -- group by pattern, count occurrences.
- Threshold check -- only act on patterns with 3+ occurrences.
- Propose updates -- for each qualifying pattern:
- If AI consistently misses a check: propose adding it to the relevant standard or guard advisory
- If AI consistently false-positives: propose relaxing the rule or adding an exception
- If humans add the same context repeatedly: propose adding it to a skill or agent instruction
- Present changes -- show proposed updates to user for approval before modifying any files.
- Apply -- update the relevant context files (standards, skills, agent instructions).
Pattern Categories
| Pattern |
Example |
Action |
| Missed check |
AI never flags missing error handling in async code |
Add to guard advisory rules |
| Over-flagging |
AI flags every single-letter variable in list comprehensions |
Add exception to naming standard |
| Missing context |
Reviewers always explain why a specific pattern is used in this codebase |
Add to project context |
| Style drift |
Reviewers consistently request a style AI does not enforce |
Add to stack standard |
Quick Reference
/ai-learn single 123 # analyze PR #123
/ai-learn batch # process all unanalyzed merged PRs
/ai-learn apply # synthesize patterns into context updates
Storage
- Learnings index:
.ai-engineering/learnings/index.jsonl
- One JSON object per line, per PR analyzed
Post-Correction Learning
When a user corrects AI behavior during a session (not just PR review):
- Capture the correction: what was wrong, what the user wanted instead
- Append the pattern to
.ai-engineering/contexts/team/lessons.md following the format in that file
- On next
/ai-learn apply, include lesson-type decisions in synthesis
$ARGUMENTS
1---2name: ai-learn3description: Use when analyzing merged PRs for AI blind spots, extracting patterns from human reviewer feedback, or applying accumulated learnings to context files.4---5
6
7# Learn
8
9## Purpose
10
11Continuous improvement from delivery outcomes. Analyzes merged PRs to find where AI missed what human reviewers caught, identifies false positives, and synthesizes recurring patterns into context updates. The feedback loop that makes the framework smarter over time.
12
13## Trigger
14
15- Command: `/ai-learn single <pr>|batch|apply`
16- Context: after PR merge (single), periodic review (batch), enough patterns accumulated (apply).
17
18## Modes
19
20### single <pr> -- Analyze one merged PR
21
221. **Fetch PR data** -- `gh pr view <pr> --json body,reviews,comments,files,additions,deletions`.
232. **Collect AI findings** -- read the AI-generated PR description, guard advisories, and verify results from the PR.
243. **Collect human feedback** -- extract all review comments, requested changes, and approval notes.
254. **Cross-reference** -- compare AI findings with human feedback:
26
27 | Category | Description |
28 |----------|-------------|
29 | **AI miss** | Human reviewer found an issue AI did not flag |
30 | **False positive** | AI flagged something human reviewer dismissed or overrode |
31 | **AI hit** | AI flagged an issue human reviewer agreed with |
32 | **Novel insight** | Human added context AI could not have known |
33
345. **Record** -- append learning entry to `.ai-engineering/learnings/index.jsonl`:
35 ```json
36 {"pr": 123, "date": "2026-03-19", "misses": 2, "false_positives": 1, "hits": 5, "patterns": ["missed-null-check", "over-flagged-naming"]}
37 ```
38
39### batch -- Process unanalyzed PRs
40
411. **Find unanalyzed** -- list merged PRs not yet in `index.jsonl`.
422. **Process each** -- run single-mode analysis for each.
433. **Summary** -- report total misses, false positives, and emerging patterns.
44
45### apply -- Synthesize into context updates
46
471. **Load learnings** -- read `.ai-engineering/learnings/index.jsonl`.
482. **Find recurring patterns** -- group by pattern, count occurrences.
493. **Threshold check** -- only act on patterns with 3+ occurrences.
504. **Propose updates** -- for each qualifying pattern:
51 - If AI consistently misses a check: propose adding it to the relevant standard or guard advisory
52 - If AI consistently false-positives: propose relaxing the rule or adding an exception
53 - If humans add the same context repeatedly: propose adding it to a skill or agent instruction
545. **Present changes** -- show proposed updates to user for approval before modifying any files.
556. **Apply** -- update the relevant context files (standards, skills, agent instructions).
56
57## Pattern Categories
58
59| Pattern | Example | Action |
60|---------|---------|--------|
61| Missed check | AI never flags missing error handling in async code | Add to guard advisory rules |
62| Over-flagging | AI flags every single-letter variable in list comprehensions | Add exception to naming standard |
63| Missing context | Reviewers always explain why a specific pattern is used in this codebase | Add to project context |
64| Style drift | Reviewers consistently request a style AI does not enforce | Add to stack standard |
65
66## Quick Reference
67
68```
69/ai-learn single 123 # analyze PR #123
70/ai-learn batch # process all unanalyzed merged PRs
71/ai-learn apply # synthesize patterns into context updates
72```
73
74## Storage
75
76- Learnings index: `.ai-engineering/learnings/index.jsonl`
77- One JSON object per line, per PR analyzed
78
79## Post-Correction Learning
80
81When a user corrects AI behavior during a session (not just PR review):
821. Capture the correction: what was wrong, what the user wanted instead
832. Append the pattern to `.ai-engineering/contexts/team/lessons.md` following the format in that file
843. On next `/ai-learn apply`, include lesson-type decisions in synthesis
85
86$ARGUMENTS
majiayu000