comprehension-report

Generate architecture narratives and requirements-adherence reports from diffs, decision journals, and issue context.

6|2|Updated Dec 19, 2025

Search Tags:#architecture #pr #comprehension #acceptance-criteria #diff-analysis #decision-journal

Ready to run

npx skills add https://github.com/synaptiai/synapti-marketplace --skill comprehension-report

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: comprehension-report
Source: https://github.com/synaptiai/synapti-marketplace/tree/main/plugins/gh-workflow/skills/comprehension-report
Command: npx skills add https://github.com/synaptiai/synapti-marketplace --skill comprehension-report

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Comprehension reports provide a clear, human-readable bridge between automated AI outputs and human understanding by detailing what was built, why decisions were made, and how the results align with original requirements.

Core Features & Use Cases

Translate diffs, decision journals, and issue context into a structured narrative suitable for PR bodies and stakeholder reviews.
Map acceptance criteria to concrete implementation evidence, enabling traceability and validation.
Surface architecture decisions and trade-offs to support human evaluation and knowledge transfer.

Quick Start

Generate a comprehension report for the current PR by summarizing the diff, linking decisions to acceptance criteria, and surfacing architecture choices.

Frequently Asked Questions about comprehension-report

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I generate an architecture narrative for a pull request from a diff?▼

Generate an architecture narrative by extracting structured diff data, mapping changes to acceptance criteria, and aggregating decision journal insights into a human-readable PR body. This translates raw code changes into a clear narrative explaining what was built and why.

How do I map acceptance criteria to implementation evidence for traceability?▼

Map acceptance criteria to implementation evidence by linking concrete diff changes directly to original issue requirements. This structured extraction validates that built features align with requested specifications, enabling automated traceability and stakeholder validation.

What is the best way to surface architecture decisions and trade-offs in code reviews?▼

Surface architecture decisions and trade-offs in code reviews by aggregating decision journal entries into a structured report. This bridges automated AI outputs and human evaluation by detailing why specific choices were made during implementation.

How do I create a requirements-adherence report from a decision journal and issue context?▼

Create a requirements-adherence report by aggregating decision journal insights and issue context, then mapping them against actual code diffs. This validates traceability and ensures the final implementation aligns with original stakeholder requirements.

Can I use diff analysis to explain why specific architecture choices were made in a PR?▼

Diff analysis extracts implementation details while decision journals provide the reasoning behind choices. Combining them generates a comprehensive PR comprehension report that details both the technical architecture built and the underlying trade-off evaluation.

When do I need a comprehension report for stakeholder reviews?▼

You need a comprehension report when stakeholders require a clear, human-readable bridge between automated code outputs and business understanding. It is necessary during PR reviews and audits to explain what was built, validate traceability, and transfer architectural knowledge.