Review Findings

Review Findings — Interactive Resolution Skill

Purpose

Walks users through findings from audit/validation reports, collects decisions via structured questions, and produces a resolution summary. Works with any skill that generates a findings report — the report file is the interface.

Key principle: This skill does not re-run checks or read source documents. It reads ONE small report file (~100-200 lines) and presents its findings interactively. The heavy analysis was already done by the producing skill.

When to Use

• After validate-requirements generates a validation report (includes both semantic and structural findings for requirements docs)
• After document-audit generates an audit report (for non-requirements docs)
• After any future skill that produces a structured findings file
• When the user wants to systematically work through findings rather than handle them ad-hoc
• When collecting decisions for later batch application via update-documents

Inputs

1. Report file path — the findings report to review (REQUIRED)
2. That's it. Everything else is in the report.

Phase 1: Setup

1.1 Read the report file

Read the full report file using the Read tool.

1.2 Detect format

Determine which skill produced the report by checking the heading:

1.3 Parse findings by category

validate-requirements format — 4 categories:

The Type column (Semantic / Structural) distinguishes which dimension each finding comes from. Use it when presenting findings to help the user understand the nature of the issue.

Also parse the "Clean" section to know which checks passed. The summary table is split into two sub-tables: "Semantic Checks" (Checks 1–11) and "Structural Checks" (Checks S1–S4).

document-audit format — 3 categories:

Generic fallback:

• Look for markdown headers containing severity keywords (Critical, High, Medium, Low, Must Fix, Should Fix, etc.)
• Parse any tables or structured text blocks under each header
• Present raw content if parsing fails

1.4 Count findings

Build a summary: total findings, count per category.

Phase 2: Entry Gate (MANDATORY)

Never start the interactive flow without asking first.

Present the summary to the user:

Found [N] findings in [report filename]:
- [N] Critical / Must Fix
- [N] Should Fix
- [N] Verify / Review Required
- [N] Gaps / Informational

Then use AskQuestion to ask how to proceed:

AskQuestion:
  id: "review-mode"
  prompt: "How would you like to review the findings?"
  options:
    - id: "all"
      label: "Walk through all findings interactively"
    - id: "critical-only"
      label: "Walk through Critical / Must Fix only"
    - id: "verify-only"
      label: "Walk through Verify / Review Required only"
    - id: "bulk-approve"
      label: "Approve all recommendations — just apply them"
    - id: "skip"
      label: "Skip — I'll handle them manually"

If "skip": End the skill. No further action.

If "bulk-approve": Skip to Phase 4 — mark all findings as "Approved as recommended" and produce the resolution summary.

If a specific category: Only walk through that category in Phase 3, skip others.

If "all": Walk through every category in Phase 3.

Phase 3: Interactive Review

Walk through findings in severity order: Critical/Must Fix first, Gaps/Informational last.

3.1 Critical / Must Fix Findings

Present each finding INDIVIDUALLY (too important to batch).

For each finding, use AskQuestion:

AskQuestion:
  id: "critical-[N]"
  prompt: "[Finding description]\n\nLocation: [section/line]\nRecommendation: [recommendation]"
  options:
    - id: "approve"
      label: "Approve fix as recommended"
    - id: "alternative"
      label: "I have a different fix (will provide details)"
    - id: "skip"
      label: "Skip — leave as-is"

If user selects "alternative": ask a follow-up question in chat for their preferred fix. Record their response as the resolution.

3.2 Should Fix Findings

Present in batches of up to 3 findings if there are many (5+). Otherwise present individually.

For each finding (or batch), use AskQuestion:

AskQuestion:
  id: "shouldfix-[N]"
  prompt: "[Finding description]\n\nRecommendation: [recommendation]"
  options:
    - id: "approve"
      label: "Approve"
    - id: "skip"
      label: "Skip — leave as-is"
    - id: "modify"
      label: "Modify recommendation"

If user selects "modify": ask for their preferred change. Record their response.

3.3 Verify / Review Required Findings

Present each finding INDIVIDUALLY (each needs a distinct decision).

For each finding, use AskQuestion:

AskQuestion:
  id: "verify-[N]"
  prompt: "[Finding description]\n\nQuestion: [question for user]"
  options:
    - id: "confirm"
      label: "Confirm — this is accurate as written"
    - id: "reject"
      label: "Reject — remove or rewrite"
    - id: "context"
      label: "Needs more context — I'll explain"

If "confirm": record as confirmed. The finding's text should get a (Source: User-confirmed) tag when fixes are applied.

If "reject": ask what should replace it, or confirm removal.

If "context": ask for the additional context, then re-present the question with the new information.

3.4 Gaps / Informational Findings

Present in batches of up to 3 findings if there are many.

For each finding (or batch), use AskQuestion:

AskQuestion:
  id: "gap-[N]"
  prompt: "[Finding description]\n\nSuggested addition: [suggestion]"
  options:
    - id: "add-requirement"
      label: "Add to requirements document"
    - id: "add-question"
      label: "Add as Open Question"
    - id: "skip"
      label: "Skip — not needed"

Phase 4: Resolution Summary

After all findings are reviewed (or bulk-approved), produce two outputs:

Output 1: Chat Summary

Display a brief summary in chat:

## Resolution Summary — [Report Name]

**Findings reviewed:** [N] of [total]
**Decisions:**
- Approved: [N]
- Confirmed: [N]
- Rejected: [N]
- Skipped: [N]
- Added as Open Question: [N]
- Modified: [N]

**Resolution file saved to:** [filepath]

### Next Step
To apply the approved fixes, use `update-documents` with the resolution file as input.

Output 2: Resolution File

Save as Resolution-[ReportName].md in the same directory as the report file.

Format:

# Resolution Summary

**Report:** [report filename]
**Reviewed on:** [date]
**Findings reviewed:** [N] of [total]

## Approved Fixes (ready to apply)

| # | Location | Original Finding | Decision | Action |
|---|----------|-----------------|----------|--------|
| 1 | [section/line] | [finding text] | Approved | [recommendation to apply] |

## Confirmed Items (add source tags)

| # | Location | Finding | Action |
|---|----------|---------|--------|
| 1 | [section/line] | [finding text] | Add `(Source: User-confirmed)` tag |

## Rejected Items (remove or rewrite)

| # | Location | Finding | User Direction |
|---|----------|---------|---------------|
| 1 | [section/line] | [finding text] | [what user said to do instead] |

## Added as Open Questions

| # | Finding | Open Question Text |
|---|---------|-------------------|
| 1 | [gap description] | [formatted as an OQ entry] |

## Skipped (no action)

| # | Location | Finding | Reason |
|---|----------|---------|--------|
| 1 | [section/line] | [finding text] | User chose to skip |

## Modified Recommendations

| # | Location | Original Recommendation | User's Alternative |
|---|----------|------------------------|-------------------|
| 1 | [section/line] | [original] | [user's version] |

Integration with Other Skills

Critical Rules

1. Always ask before starting. Phase 2 Entry Gate is mandatory. Never jump into the interactive flow without the user's explicit choice.
2. Critical findings are always individual. Never batch Critical/Must Fix findings — each one deserves its own question.
3. Record everything. Every decision (including "skip") is recorded in the resolution file. Nothing is lost.
4. Don't fix — collect decisions. This skill collects user decisions. It does not modify the requirements document or any other file except the resolution summary.
5. Respect the user's choice. If they say "skip", stop. If they say "critical only", don't sneak in other categories.
6. Resolution file is the handoff. The resolution file is structured so update-documents (or a human) can apply fixes without re-reading the original report.
7. Format-agnostic fallback. If the report format is unrecognized, present findings as raw text with generic approve/skip options. Never fail because of an unexpected format.