# Review Findings

> Interactively walks users through findings from any audit or validation report (validate-requirements, document-audit, or future skills). Reads the report file, detects its format, presents findings via AskQuestion for user decisions, and produces a resolution summary. Use after any skill that generates a findings report, or standalone against any structured findings markdown file.

- **Type:** Skill
- **Install:** `agentstack add skill-drivestream-lab-prayog-skills-review-findings`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [drivestream-lab](https://agentstack.voostack.com/s/drivestream-lab)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [drivestream-lab](https://github.com/drivestream-lab)
- **Source:** https://github.com/drivestream-lab/prayog-skills/tree/main/skills/requirements/review-findings

## Install

```sh
agentstack add skill-drivestream-lab-prayog-skills-review-findings
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```markdown
# 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](https://github.com/drivestream-lab)
- **Source:** [drivestream-lab/prayog-skills](https://github.com/drivestream-lab/prayog-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-drivestream-lab-prayog-skills-review-findings
- Seller: https://agentstack.voostack.com/s/drivestream-lab
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.