# ao-plan-integrate-review

name: ao-plan-integrate-review
category: core
description: Apply review decisions from `.review.md` into the canonical plan and regenerate preview
invokes: [ao-state, ao-plan-preview, ao-plan-review-import]
invoked_by: [ao-planning, ao-worker]
references: [confidence.md, completion-gate.md]

---

## Purpose

Integrate structured review feedback into the canonical plan file, update the plan with accepted changes, insert open questions, ensure blockers remain visible, and regenerate the stakeholder preview.

## When to Use

- After `ao-plan-review-import` has created a `.review.md` file
- When iterating on a plan after stakeholder feedback
- As part of the plan review round-trip workflow

## Input Files

All files in `.agent/ops/issues/references/`:

| File | Purpose |
|------|---------|
| `<issue>.plan.md` | Canonical plan (source of truth) |
| `<issue>.review.md` | Structured review feedback |
| `<issue>.preview.md` | Stakeholder-friendly preview (will be regenerated) |

## Integration Rules

### 1. Accepted Changes

Changes marked as accepted are applied to the plan:

```markdown
## Accepted Changes
- [Section: Overview] Clarify success metrics for the feature
```

**Action**: Update the Overview section with the clarification.

### 2. Open Questions

Questions are inserted into a dedicated section:

```markdown
## Open Questions (from review)

- [ ] [Data Model] Should we normalize table Y or keep it denormalized?
- [ ] [API] What authentication method should the endpoint use?
```

**Placement**: After the relevant section, or in a consolidated "Open Questions" section at the end.

### 3. Blockers

Blockers are prominently displayed at the top of the plan:

```markdown
# Plan: FEAT-0123

> ⚠️ **BLOCKERS** (must resolve before implementation)
> - [API] Security review required for exposed endpoint Z
> - [Dependencies] License compatibility check needed

## Overview
...
```

**Rule**: Implementation MUST NOT proceed while blockers exist.

### 4. Conflicts

Conflicts remain as open questions with both positions documented:

```markdown
## Open Questions (from review)

- [ ] [Architecture] Microservices vs monolith — alice and bob disagree
  - alice: "Microservices for better scaling"
  - bob: "Monolith for simplicity"
  - **Requires human decision**
```

## Workflow

```
┌─────────────────────────────────────────────────────────────────────┐
│                      PLAN INTEGRATE REVIEW                         │
└─────────────────────────────────────────────────────────────────────┘

1. READ
   ├── .agent/ops/issues/references/<issue>.plan.md (canonical plan)
   └── .agent/ops/issues/references/<issue>.review.md (structured feedback)

2. VALIDATE
   ├── Review file exists and has content
   ├── Plan file exists
   └── No schema violations

3. APPLY CHANGES
   ├── Insert accepted changes into relevant sections
   ├── Add open questions section
   ├── Prepend blockers banner if any exist
   └── Document conflicts with both positions

4. UPDATE PLAN
   └── Write updated .plan.md

5. REGENERATE PREVIEW
   └── Invoke ao-plan-preview → .preview.md

6. LOG INTEGRATION
   └── Add entry to plan's changelog section:
       "2026-01-25: Integrated review feedback from PR #42"
```

## Output

Updated files in `.agent/ops/issues/references/`:

| File | State |
|------|-------|
| `<issue>.plan.md` | Updated with review feedback |
| `<issue>.preview.md` | Regenerated from updated plan |
| `<issue>.review.md` | Unchanged (preserved for audit) |

## Confidence Impact

Review integration can affect issue confidence:

| Review Outcome | Confidence Impact |
|----------------|-------------------|
| All accepted, no blockers | May increase confidence |
| Minor open questions | No change |
| Significant open questions | Consider lowering confidence |
| Blockers present | **Cannot proceed** — resolve first |
| Conflicts present | Lower confidence until resolved |

## Example Invocation

```
/ao-plan-integrate-review FEAT-0123

Integrating review for FEAT-0123...

Review Summary:
- 3 accepted changes → applied
- 5 open questions → inserted
- 1 blocker → banner added
- 1 conflict → documented

Plan updated: .agent/ops/issues/references/FEAT-0123.plan.md
Preview regenerated: .agent/ops/issues/references/FEAT-0123.preview.md

⚠️ BLOCKERS PRESENT — resolve before implementation:
- [API] Security review required for exposed endpoint Z

Next steps:
1. Address blocker(s)
2. Resolve open questions
3. Re-run review cycle if needed
4. Proceed to implementation when clear
```

## Iteration Support

Multiple review cycles are supported:

```
Plan v1 → Preview → Review #1 → Integrate → Plan v2
                                    ↓
Plan v2 → Preview → Review #2 → Integrate → Plan v3
                                    ↓
Plan v3 (approved) → Implementation
```

Each integration:
- Preserves previous review files (rename to `<issue>.review-1.md`, etc.)
- Logs iteration in plan changelog
- Clears resolved items from the new review

## Error Handling

| Condition | Action |
|-----------|--------|
| No review file | Prompt to run import first |
| No plan file | Error — cannot integrate without plan |
| Blocker resolution unclear | Keep blocker visible, ask human |
| Section not found in plan | Create section or add to "Other Feedback" |

## AO Worker Integration

The Worker agent respects this skill's output:

```
IF blocker_banner_present:
    STOP — ask human to resolve blockers
    
IF open_questions > threshold:
    LOWER confidence
    REQUIRE human review of plan before implementation
    
IF all_clear:
    PROCEED with implementation
```

## Related Skills

- `ao-plan-review-import` — Creates the review file
- `ao-plan-preview` — Generates stakeholder preview
- `ao-planning` — Creates the initial plan
- `ao-implementation` — Consumes approved plan
