# PR Feedback Guidelines (Parlant-Style)

This directory contains structured guidelines that help Claude correctly classify and respond to PR feedback. The approach is inspired by [Parlant](https://github.com/emcie-co/parlant) - moving from "prompt and hope" to "guidelines and verify".

## Philosophy

Instead of relying on implicit understanding, these guidelines provide explicit rules that:
1. **Activate contextually** based on feedback content
2. **Classify intent** before taking action
3. **Enable self-critique** to verify compliance before acting

## Directory Structure

```
.claude/knowledge/pr-feedback/
├── README.md                      # This file
├── priority-rules.md              # CRITICAL/HIGH/MEDIUM/LOW/NITPICK
├── intent-detection.md            # QUESTION vs CHANGE_REQUEST
├── conflict-handling.md           # When reviewers disagree
├── source-handling.md             # Bot vs human differentiation
├── feedback-verification.md       # Checklist to verify classification
├── branch-creation.md             # ALWAYS branch from main
├── iterate-pr-feedback.md         # Full iteration workflow
└── plan-first-pattern.md          # Think before you act
```

## How Guidelines Work

### 1. Pattern Matching

Each guideline contains condition-action pairs:

```
CONDITION: Feedback contains "security", "vulnerability", "injection"
→ CLASSIFICATION: CRITICAL
→ ACTION: Must fix immediately, add security test case
```

### 2. Intent Detection

Before making code changes, determine what the reviewer wants:

| Pattern | Intent | Response |
|---------|--------|----------|
| "Why did you..." | QUESTION | Explain, don't change code |
| "Please add..." | CHANGE_REQUEST | Make the change |
| Multiple conflicting reviews | CONFLICT | Escalate to human |

### 3. Self-Critique

Before acting on any feedback item, verify the classification is correct:
- Is this actually a security issue?
- Is the reviewer asking why, or telling me to change?
- Has another reviewer said the opposite?

## Usage

When iterating on PR feedback:

1. **Load Guidelines**: Read `.claude/knowledge/pr-feedback/`
2. **Classify Each Item**: Apply rules to determine priority and intent
3. **Self-Critique**: Verify classification before acting
4. **Take Appropriate Action**: Based on verified classification

## Benefits

- **Fewer misunderstandings**: Explicit rules catch edge cases
- **Consistent behavior**: Same classification logic every time
- **Auditable decisions**: Can explain why each item was classified
- **Reduced iteration cycles**: Correct response on first try

## Integration with Engineering Standards

These guidelines complement the project's [Engineering Standards](../../standards/ENGINEERING_STANDARDS.md).
When addressing feedback, ensure changes adhere to:
- **Type hints** (ENGINEERING_STANDARDS.md §Python Best Practices)
- **Error handling** (ENGINEERING_STANDARDS.md §Python Best Practices)
- **Testing requirements** (ENGINEERING_STANDARDS.md §Testing Requirements)

## Related

- `.claude/prompts/iterate-pr-reviews.md` - Main iteration prompt (uses these guidelines)
- `.claude/knowledge/automation/pr-iteration.md` - PR iteration documentation
