agentleFS
drivestream-labdrivestream-lab/prayog-skills/skills/requirements/review-findings/SKILL.md

review-findings

Skill2 starsChanged 4 months agoMITView on GitHub

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 each finding as a decision brief (issue, example, recommendation+why, options with pros/cons) via AskQuestion, and produces a resolution summary with VF→CHG linkage. Use after any skill that generates a findings report, or standalone against any structured findings markdown file.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 10 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After validate-requirements generates a validation report

    line 19
  2. Very specific:

    After document-audit generates an audit report

    line 20
  3. Distinctive:

    When the user wants to systematically work through findings rather than handle them ad-hoc

    line 21
  4. Distinctive:

    When collecting decisions for later batch application to the PRD or integration stubs

    line 22
  5. Distinctive:

    Read the full report file using the Read tool.

    line 35
  6. Distinctive:

    Look for markdown headers containing severity keywords (Critical, High, Medium, Low, Must Fix, Should Fix, etc.)

    line 79
  7. Distinctive:

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

    line 131
  8. Distinctive:

    Should Fix / Gaps may use a shorter brief (issue + recommendation + why) and batch up to 3 when there are 5+ findings — still include …

    line 165
  9. Very specific:

    If user selects B or D: capture their wording as the action text.

    line 188
  10. Very specific:

    If "confirm": record confirmed.

    line 215
  11. Distinctive:

    If "reject": ask replacement or confirm removal.

    line 216
  12. Distinctive:

    If "context": ask for context, then re-present.

    line 217
  13. Distinctive:

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

    line 242
  14. Very specific:

    Record everything: Every decision (including skip) is in the resolution file with VF and CHG where applicable.

    line 345
  15. Distinctive:

    Don't fix — collect decisions: Only write the resolution summary file.

    line 346
  16. Very specific:

    When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before …

    line 356
  17. Very specific:

    Follow prayog-skills/references/forge-side-effects.md#content-producers when this stage's pin has forge.commit_workspace other than …

    line 360

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Conventions: prayog-skills/references/id-conventions.md, prayog-skills/references/artifact-write-contract.md.

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). Prefer canonical prd/reports/Validation-Report-{INIT}.md.
  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:

HeadingFormatProducer
# Requirements Reviewvalidate-requirements (combined semantic + structural)validate-requirements skill
# Requirements Accuracy Reviewvalidate-requirements (legacy)validate-requirements skill
# Document Audit Reportdocument-auditdocument-audit skill
OthergenericUnknown — 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:

CategorySection header patternSeverityId columnTable Columns
Critical## CriticalMUST FIXVF (or legacy #)VF, Type, Location, Target, Check, Finding, Source Says, Doc Claims, Example, Recommendation
Should Fix## Should FixSHOULD FIXVFVF, Type, Location, Target, Check, Finding, Recommendation
Verify## VerifyVERIFYVFVF, Type, Location, Target, Check, Finding, Question for User
Gaps## GapsGAPVFVF, Type, Location, Target, Check, Finding, Suggested Addition

Legacy reports with only # instead of VF: assign stable VF-{nn} for this resolution pass (map #1 → VF-01) and record the mapping in the resolution file.

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:

CategorySeverityStructure
Must Fix (HIGH)MUST FIXText blocks: type (STALE/CONTRADICTION/BROKEN REF), marker, evidence, recommendation, confidence
Review Required (MEDIUM)VERIFYSame structure
Informational (LOW)INFOSame structure

Assign VF-{nn} when missing.

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; still assign VF-*

1.4 Count findings

Build a summary: total open findings, count per category. Exclude resolved rows.

1.5 Resolve initiative id

From report front matter / filename / PRD path. Needed for canonical Resolution-{INIT}.md output.


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] (report_revision [N] if present):
- [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 recommended option; assign CHG-* per finding; 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.

Decision brief (REQUIRED for Critical and Verify)

For each finding, present in chat before AskQuestion:

### [VF-id] — [severity]

**Issue:** [what is wrong — from Finding]
**Target:** [REQ-* / CAP-* / OQ-* / section]
**Location:** [section/line]
**Check:** [check #]
**Evidence / example:** [Source Says vs Doc Claims, or Example column, or a concrete illustration]
**Recommendation:** [recommended fix]
**Why this recommendation:** [1–2 sentences — risk if ignored, consistency with sources]

**Options:**
| Option | Summary | Pros | Cons |
|--------|---------|------|------|
| A (recommended) | [apply recommendation] | [pros] | [cons] |
| B | [plausible alternative] | [pros] | [cons] |
| C | Skip / leave as-is | [pros] | [cons] |
| D | Custom (user will specify) | — | — |

Should Fix / Gaps may use a shorter brief (issue + recommendation + why) and batch up to 3 when there are 5+ findings — still include options with pros/cons for the batch decision.

3.1 Critical / Must Fix Findings

Present each finding INDIVIDUALLY (never batch).

AskQuestion:
  id: "critical-[VF-id]"
  prompt: "[VF-id] [short issue]\n\nChoose an option:"
  options:
    - id: "A"
      label: "A — Apply recommendation"
    - id: "B"
      label: "B — [alternative summary]"
    - id: "C"
      label: "C — Skip / leave as-is"
    - id: "D"
      label: "D — Custom (I'll specify)"

If user selects B or D: capture their wording as the action text. Record chosen_option, rationale (ask briefly if missing), and assign CHG-{nn}.

3.2 Should Fix Findings

Present in batches of up to 3 if there are many (5+). Otherwise individually. Same option pattern (A/B/C/D); shorter brief allowed.

3.3 Verify / Review Required Findings

Present each finding INDIVIDUALLY with full decision brief.

AskQuestion:
  id: "verify-[VF-id]"
  prompt: "[VF-id] [question for user]"
  options:
    - id: "confirm"
      label: "Confirm — accurate as written (tag Source: User-confirmed)"
    - id: "reject"
      label: "Reject — remove or rewrite"
    - id: "context"
      label: "Needs more context — I'll explain"
    - id: "skip"
      label: "Skip for now"

If "confirm": record confirmed; action = add (Source: User-confirmed) when applied. If "reject": ask replacement or confirm removal. If "context": ask for context, then re-present.

3.4 Gaps / Informational Findings

Present in batches of up to 3 when many.

AskQuestion:
  id: "gap-[VF-id]"
  prompt: "[VF-id] [suggested addition]"
  options:
    - id: "add-requirement"
      label: "Add to requirements (assign REQ-* / CAP-* if needed)"
    - id: "add-oq"
      label: "Add as Open Question OQ-*"
    - id: "skip"
      label: "Skip — not needed"
    - id: "custom"
      label: "Custom"

Phase 4: Resolution Summary

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

Output 1: Chat Summary

## Resolution Summary — [INIT]

**Report:** [canonical validation path] (report_revision [N])
**Findings reviewed:** [N] of [total]
**Decisions:**
- Approved (option A or equivalent): [N]
- Alternative / custom: [N]
- Confirmed: [N]
- Rejected: [N]
- Skipped: [N]
- Added as OQ: [N]

**Resolution file:** [canonical Resolution path] (overwritten)

### Next Step
Apply approved `CHG-*` via `update-documents`, then re-run `validate-requirements`
in incremental mode against the **same** Validation-Report path.

Output 2: Resolution File

Canonical path: {reports_dir}/Resolution-{INIT}.md

Overwrite this path. Never Resolution-…-revN.md or Resolution-Validation-Report-….md long derivatives.

Format:

# Resolution Summary

**Report:** [canonical Validation-Report path]
**Initiative:** [INIT]
**Reviewed on:** [date]
**resolution_revision:** [N]
**Findings reviewed:** [N] of [total]

## Decisions

| CHG | VF | Severity | Target | Chosen option | Rationale | Action to apply |
|-----|-----|----------|--------|---------------|-----------|-----------------|
| CHG-01 | VF-01 | Critical | REQ-07 | A | [why] | [exact apply text] |
| CHG-02 | VF-04 | Verify | CAP-02 | confirm | [why] | Add (Source: User-confirmed) |

## Approved Fixes (ready to apply)

| CHG | VF | Type | Location | Original Finding | Decision | Action |
|-----|-----|------|----------|------------------|----------|--------|
| CHG-01 | VF-01 | Semantic | [section] | [finding] | Option A | [recommendation to apply] |

## Confirmed Items (add source tags)

| CHG | VF | Type | Location | Finding | Action |
|-----|-----|------|----------|---------|--------|
| CHG-02 | VF-04 | … | … | … | Add `(Source: User-confirmed)` tag |

## Rejected Items (remove or rewrite)

| CHG | VF | Type | Location | Finding | User Direction |
|-----|-----|------|----------|---------|----------------|
| … | … | … | … | … | … |

## Added as Open Questions

| CHG | VF | Finding | OQ id | Open Question Text |
|-----|-----|---------|-------|---------------------|
| … | … | … | OQ-03 | … |

## Skipped (no action)

| VF | Type | Location | Finding | Reason |
|----|------|----------|---------|--------|
| … | … | … | … | User chose skip |

## Modified / custom recommendations

| CHG | VF | Original Recommendation | User's Alternative | Rationale |
|-----|-----|-------------------------|-------------------|-----------|
| … | … | … | … | … |

Integration with Other Skills

ContextHow it's called
After validate-requirementsUser runs validation → report generated → invoke with canonical Validation-Report path
After document-auditSame pattern
Lab workflowResolution feeds PRD edits + stubs via update-documents; then incremental validate
StandaloneUser points it at any findings report file

Critical Rules

  1. Always ask before starting. Phase 2 Entry Gate is mandatory.
  2. Critical findings are always individual with a full decision brief.
  3. Record everything. Every decision (including skip) is in the resolution file with VF and CHG where applicable.
  4. Don't fix — collect decisions. Only write the resolution summary file.
  5. Respect the user's choice. Skip / category filters are honored.
  6. Canonical resolution path. Overwrite Resolution-{INIT}.md only.
  7. Format-agnostic fallback. Unrecognized format → raw text + generic options + assigned VF-*.
  8. Ignore resolved history. Rows under ## Resolved are not open findings.
  9. Options need pros/cons in the brief so the user can choose deliberately.

Workflow handoff

  1. Append/emit the envelope from prayog-skills/references/handoff-envelope.md to the Resolution file. Use stage review-findings.
  2. When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before exit. Leaving the baton empty is a failed stage for automated consumers. artifact.path remains the workspace skill output, not the baton path. See prayog-skills/references/handoff-envelope.md (Orchestrator baton).
  3. Derive next_candidates and human_checkpoint from pinned root workflow.yaml for (stage: review-findings, outcome) per prayog-skills/references/handoff-envelope.md (Derive from pinned workflow). Set human_checkpoint: true only when the resolved next node's type is human-checkpoint — never because the artifact "should be reviewed."
  4. Follow prayog-skills/references/forge-side-effects.md#content-producers when this stage's pin has forge.commit_workspace other than disabled or next is an external-action with forge.requires — fill handoff.forge / recommend the matching /forge skill; do not treat local CLI as skill success.

Transitions: pinned root workflow.yaml for this stage (SSOT). Human or agent may run this skill; legality and auto-dispatch follow dispatch + delivery contract + latest handoff.

Record unresolved VF-* under blockers; never encode a user decision only in chat. next_candidates never authorize invoke.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.