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 report file 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
• After document-audit generates an audit report
• When the user wants to systematically work through findings rather than handle them ad-hoc
• When collecting decisions for later batch application to the PRD or integration stubs

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:

| Heading | Format | Producer | |---|---|---| | # Requirements Review | validate-requirements (combined semantic + structural) | validate-requirements skill | | # Requirements Accuracy Review | validate-requirements (legacy) | validate-requirements skill | | # Document Audit Report | document-audit | document-audit skill | | Other | generic | Unknown — use fallback parsing |

1.3 Parse findings by category

Do not treat ## Resolved as open findings. That section records items fixed since a prior report — parse for context only, never walk the user through resolved rows.

validate-requirements format — 4 categories:

| Category | Section header pattern | Severity | Table Columns | |---|---|---|---| | Critical | ## Critical | MUST FIX | #, Type, Location, Check, Finding, Source Says, Doc Claims, Recommendation | | Should Fix | ## Should Fix | SHOULD FIX | #, Type, Location, Check, Finding, Recommendation | | Verify | ## Verify | VERIFY | #, Type, Location, Check, Finding, Question for User | | Gaps | ## Gaps | GAP | #, Type, Location, Check, Finding, Suggested Addition |

Legacy reports without a Type column: treat Type as unknown and continue.

Also parse the ## Clean section to know which checks passed.

Skip sections that contain only prose like "No Critical findings." with no table rows.

document-audit format — 3 categories:

| Category | Severity | Structure | |---|---|---| | Must Fix (HIGH) | MUST FIX | Text blocks: type (STALE/CONTRADICTION/BROKEN REF), marker, evidence, recommendation, confidence | | Review Required (MEDIUM) | VERIFY | Same structure | | Informational (LOW) | INFO | Same structure |

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 open findings, count per category. Exclude resolved rows.

---

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. If AskQuestion is unavailable, present the same options in chat and wait for the user's choice.

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.

For each finding, show: #, Type (if present), Location, Finding, and the relevant action column (Recommendation / Question for User / Suggested Addition).

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
Apply approved fixes to the PRD and integration stubs, then re-run `validate-requirements` with this report as the prior report (incremental mode).

Output 2: Resolution File

Save as Resolution-[ReportName].md in the same directory as the report file (e.g. prd/reports/Resolution-INIT-PRAYOG-001.md when the report is Validation-Report-INIT-PRAYOG-001.md).

Format:

# Resolution Summary

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

## Approved Fixes (ready to apply)

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

## Confirmed Items (add source tags)

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

## Rejected Items (remove or rewrite)

| # | Type | Location | Finding | User Direction |
|---|------|----------|---------|---------------|
| 1 | [Semantic/Structural] | [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)

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

## Modified Recommendations

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

---

Integration with Other Skills

| Context | How it's called | |---|---| | After validate-requirements | User runs validation → report generated → next steps suggest review-findings → user invokes it with the report path | | After document-audit | Same pattern — audit report generated → user invokes review-findings | | Lab workflow | Resolution file feeds PRD edits + cross-service-lab.md / per-repo 03-integrations stub updates; then incremental validate-requirements | | Standalone | User points it at any findings report file |

---

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 a human or agent 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.
8. Ignore resolved history. Rows under ## Resolved are not open findings — do not count or walk through them.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: drivestream-lab
• Source: drivestream-lab/prayog-skills
• License: MIT

Install and usage instructions live in the source repository linked above.