From reconciliation-audit
Multi-document reconciliation engine. Cross-references PRD, UX Design System, and Mock documents to detect conflicts, coverage gaps, self-additions, naming drift, cascade violations, and specificity gaps. Generates a markdown report, interactive HTML dashboard, and optionally editable Excalidraw diagrams.
How this skill is triggered — by the user, by Claude, or both
Slash command
/reconciliation-audit:reconciliation-auditThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Cross-reference product documents to find misalignments **before** code is written. PRD is always the source of truth. Compare it against one or both satellite documents:
Cross-reference product documents to find misalignments before code is written. PRD is always the source of truth. Compare it against one or both satellite documents:
This skill answers:
| Use reconciliation-audit when... | Use wireframe-audit when... |
|---|---|
| You have 2-3 documents (PRD, UX, Mock) and need to check alignment before building | You have HTML wireframes and need a detailed implementation audit |
| Mock is a markdown description, screenshots, OR HTML | Wireframe is HTML only — the skill reads the actual DOM with Puppeteer |
| You want to compare PRD vs UX (no mock at all) | You always need HTML wireframe + PRD and/or UX |
| You need trilateral cascade detection (PRD -> UX -> Mock drift) | You need visual evidence with screenshot markers per component |
| You want Excalidraw diagrams and a verification map | You want a dashboard with findings explorer + coverage heatmap + screenshot gallery |
| Focus: document-level alignment + internal consistency | Focus: implementation correctness of built wireframes |
The two skills are complementary: run reconciliation-audit first to align documents, then wireframe-audit after HTML wireframes are built to verify implementation quality.
| # | Input | Required | Description |
|---|---|---|---|
| 1 | PRD file | Yes | Markdown file with product requirements, features, pages, flows |
| 2 | UX Design System file | No | Markdown file with design tokens, components, layout, states, responsive behavior |
| 3 | Mock file or folder | No | Markdown description of mocks, annotated screenshots, or HTML mock files |
| 4 | Previous reconciliation folder | No | Enables incremental delta mode — loads reconciliation-data.json from a prior run, carries forward unchanged requirements, and only re-analyzes new/changed ones. User specifies which requirements or sections changed. Generates a delta-summary.md showing new, resolved, and changed findings. |
| 5 | Generate Excalidraw diagrams | No | If not provided by the user, ask: "Would you like to generate Excalidraw diagrams (coverage heatmap, Venn overlap, traceability flow, gap treemap)? These are optional and can be generated later from the JSON data." Accepts yes/no. Defaults to no if the user does not specify. |
| Rules: |
.html files. No user prompt needed — it is part of the standard workflow. Requires npx puppeteer to be available. If Puppeteer is not installed, skip gracefully with a warning.| Mode | Documents | Comparison Directions |
|---|---|---|
| Bilateral: PRD+UX | PRD, UX | PRD <-> UX |
| Bilateral: PRD+Mock | PRD, Mock | PRD <-> Mock |
| Trilateral: Full | PRD, UX, Mock | PRD <-> UX, PRD <-> Mock, UX <-> Mock, PRD -> UX -> Mock cascade |
All written to docs/audit/reconciliation/{analysis_name}/ where {analysis_name} is kebab-case [prd-title]-[YYYY-MM-DD].
docs/audit/reconciliation/{analysis_name}/
├── reconciliation.md # Main markdown report
├── reconciliation-data.json # Structured data (single source of truth for all visual outputs)
├── reconciliation-matrix.html # Interactive HTML dashboard (loads reconciliation-data.json)
├── visual-verification/ # Only if HTML mocks detected (Puppeteer auto-runs)
│ ├── visual-verify.mjs # Generated Puppeteer script
│ ├── verification-results.json # DOM verification results per component
│ ├── verification-map.html # Interactive screenshot viewer with bounding box overlays
│ ├── mock-dashboard.png # Full-page screenshot per HTML mock
│ └── mock-settings.png # (one .png per .html mock file)
├── diagrams/ # Only if user opts in to diagram generation
│ ├── coverage-heatmap.excalidraw # Requirement x Document coverage grid
│ ├── venn-overlap.excalidraw # 2 or 3 circle document overlap
│ ├── traceability-flow.excalidraw # Requirement flow: PRD -> UX -> Mock
│ └── gap-treemap.excalidraw # Findings by area, sized by count
└── delta-summary.md # Only in delta mode — shows new/resolved/changed findings + score trends
Problem: Large HTML files with inline data exhaust the output token budget, causing truncated or missing outputs.
Solution: All visual outputs (HTML, Excalidraw) are driven by a single reconciliation-data.json file. The HTML is a static template that loads this JSON at runtime. This means:
reconciliation-data.json via fetch() and renders dynamically. Template is defined in reference.md.Outputs must be generated in this exact order to prevent token exhaustion:
fetch('./reconciliation-data.json') to load data at runtime.Problem: Analysis of large documents consumes most of the context window. By the time output generation starts, context runs out and later phases are skipped — leaving empty or missing files.
Solution: Phase checkpointing with reconciliation-data.json as the recovery anchor.
The workflow is split into two independent stages that can run in separate sessions if needed:
Stage 1 — Analysis (Phases 0-7): Read documents, extract inventories, run comparisons, generate reconciliation-data.json. This is the context-heavy stage. Once the JSON is written to disk, all analysis is persisted.
Stage 2 — Output Generation (Phases 8-12): Read only reconciliation-data.json (not the original documents). Generate MD, HTML, and Excalidraw outputs. This stage is context-light because it only reads compact JSON.
reconciliation-data.json as early as possible — immediately after Phase 6 scoring completes. Do not wait until all outputs are generated.docs/audit/reconciliation/{analysis_name}/reconciliation-data.json". The skill resumes from Phase 8.Before starting, estimate context pressure:
| Document size | Estimated context cost | Can complete in one session? |
|---|---|---|
| Small (each <2000 lines total) | ~30% of context | Yes — all phases |
| Medium (2000-5000 lines total) | ~50% of context | Likely — may skip Excalidraw |
| Large (>5000 lines total) | ~70%+ of context | Split into 2 sessions |
For medium/large documents, proactively warn the user at the start:
"These documents are large. I'll generate the analysis JSON and MD report first. If context runs low, I'll save progress and you can run a follow-up session for the HTML and diagrams."
When the user asks to resume or generate outputs from an existing JSON:
reconciliation-data.json — do NOT read the original documentsAll findings use descriptive names as primary labels. No code abbreviations.
| # | Category | Key | Color | Hex | Scope | Description |
|---|---|---|---|---|---|---|
| 1 | Conflict | conflict | Red | #ef4444 | Any 2+ docs | Two or more documents define contradictory behavior for the same feature |
| 2 | Naming Drift | naming-drift | Violet | #7c3aed | Any 2+ docs | Same concept uses different names across documents |
| 3 | Coverage Gap | coverage-gap | Blue | #3b82f6 | PRD -> target | PRD requires something the target document does not define |
| 4 | Scope Addition | scope-addition | Orange | #f97316 | Target -> PRD | A satellite document defines something with no PRD justification |
| 5 | Cascade Violation | cascade-violation | Pink | #ec4899 | PRD -> UX -> Mock | Progressive drift: PRD says X, UX interpreted as Y, Mock built Z |
| 6 | Specificity Gap | specificity-gap | Amber | #f59e0b | Downstream -> source | A downstream document invented details not present in its source |
| # | Category | Key | Color | Hex | Scope |
|---|---|---|---|---|---|
| 7 | PRD Internal Issue | prd-internal | Indigo | #6366f1 | Contradictions, ambiguity, or gaps within the PRD itself |
| 8 | UX Internal Issue | ux-internal | Teal | #14b8a6 | Contradictions, ambiguity, or undefined references within UX |
| 9 | Mock Internal Issue | mock-internal | Slate | #64748b | Contradictions, inconsistencies, or orphan elements within the Mock |
| Level | Meaning |
|---|---|
| Blocker | Documents directly contradict — cannot proceed to next phase until resolved |
| Major | Significant gap or ambiguity — likely causes rework if not resolved |
| Minor | Terminology inconsistency or minor omission — low risk |
conflict-1, conflict-2, naming-drift-1, coverage-gap-1, scope-addition-1, cascade-violation-1, specificity-gap-1, prd-internal-1, ux-internal-1, mock-internal-1reconciliation.md and reconciliation-matrix.html[PRD<>UX], [PRD<>Mock], [UX<>Mock], [PRD>UX>Mock]docsTag values always means two different finding IDs.0A. Resume check — Before anything else, check if this is a resume session:
reconciliation-data.json, this is a resume session0B. Fresh session — If no existing JSON:
docs/audit/reconciliation/{analysis_name}/reconciliation-data.json will be the checkpointgenerateDiagrams (boolean). If false, skip Phase 10 entirely..html files, set visualVerification = true and Phase 3B will run automatically. If no HTML mocks, set visualVerification = false and skip Phase 3B.Parse the PRD into structured inventories:
P1. Functional Requirements
| Field | Description |
|---|---|
| ID | Requirement identifier (FR-1, REQ-1, or auto-assigned) |
| Title | Short name |
| Description | Full requirement text |
| Page/View | Which page it belongs to (if specified) |
| Priority | Must-have / Should-have / Nice-to-have (if specified) |
P2. Page/View Registry
| Field | Description |
|---|---|
| Name | Page or view name |
| Purpose | What it does |
| Requirements | List of FR IDs that apply |
P3. Component Mentions
| Field | Description |
|---|---|
| Component | Name as mentioned in PRD (e.g., "data table", "filter dropdown") |
| Context | Where/how it's mentioned |
| Requirements | FR IDs that reference it |
P4. State Requirements
| Field | Description |
|---|---|
| State | empty, error, loading, success, disabled, etc. |
| Component/Page | Where this state applies |
| Requirement | FR ID |
P5. Flow Definitions
| Field | Description |
|---|---|
| Flow name | User journey name |
| Steps | Ordered list of steps/pages |
| Requirements | FR IDs |
P6. Business Rules
| Field | Description |
|---|---|
| Rule | Validation, permission, limit, constraint |
| Applies to | Component/page |
| Requirement | FR ID |
P7. Page Sections (conditional — only if PRD describes page-level structure)
| Field | Description |
|---|---|
| Page | Page/view name |
| Section | Named area, region, or panel |
| Contents | What PRD says belongs in this section |
| Requirements | FR IDs governing this section |
Parse the UX document into structured inventories. Only extract inventories that the document defines — skip any inventory the UX does not address.
U1. Design Tokens — CSS variables, colors, spacing, shadows, radii
U2. Typography — Font families, sizes, weights, line-heights per element type
U3. Component Registry
| Field | Description |
|---|---|
| Name | Component name as defined in UX |
| Variants | List of defined variants |
| Sub-components | Child components |
| Props/Config | Configurable properties |
Completeness note: When the UX document mentions a component by name but does not define its behavior, variants, or states, mark it as mentioned-only rather than defined. During Phase 4A, a mentioned-only component does NOT satisfy a PRD requirement that specifies interaction details.
U4. Component States — Which states each component supports (hover, focus, disabled, loading, empty, error)
U5. Page/View Definitions — Pages the UX defines, with component placement
U6. Layout Specs — Grid, dimensions, spacing, responsive breakpoints
U7. Interaction Patterns — Transitions, animations, gestures, keyboard behavior
U8. Responsive Behavior — Breakpoints, what changes at each
U9. Page Composition (conditional)
| Field | Description |
|---|---|
| Page | Page/view name |
| Sections | Named areas/regions within the page |
| Component placement | Which components appear in each section |
| Hierarchy | Parent-child nesting of layout and components |
U10. Component-Page Matrix (conditional)
| Field | Description |
|---|---|
| Component | Component name |
| Pages used | List of pages where this component appears |
| Variants per page | Which variant is used on each page |
U11. Navigation Map (conditional)
| Field | Description |
|---|---|
| Source page | Starting page/view |
| Target page | Destination page/view |
| Trigger | What initiates the navigation |
| Conditions | Guards or prerequisites |
Parse mock documents into structured inventories. Mocks may be markdown descriptions, annotated screenshot references, or HTML files.
K1. Screen Registry
| Field | Description |
|---|---|
| Screen name | Name or label of the screen/view |
| Description | What the screen shows |
| Source | File or reference |
K2. Visual Component Inventory
| Field | Description |
|---|---|
| Component | What's visually present (button, table, card, modal, etc.) |
| Screen | Which screen it appears on |
| Visual properties | Size, color, position, text content as visible |
| Variants shown | Which variant is rendered |
Functional completeness: For each component, assess whether the Mock implements it fully or only partially. Record as full (complete interaction surface present), trigger-only (button/icon/link present but no interaction surface behind it), or partial (some elements present but key behaviors missing) in the Variants shown field. During Phase 4C, a trigger-only or partial component does NOT satisfy a PRD requirement that specifies interactive behavior.
K3. Screen Layout
| Field | Description |
|---|---|
| Screen | Screen name |
| Sections | Visual areas/regions |
| Component placement | What appears where |
| Visual hierarchy | Nesting, ordering |
K4. State Representations
| Field | Description |
|---|---|
| Screen | Screen name |
| State shown | Which state is rendered (empty, loading, error, filled, etc.) |
| Visual treatment | How the state looks |
K5. Navigation/Flow Shown
| Field | Description |
|---|---|
| Source screen | Starting screen |
| Target screen | Destination screen |
| Trigger element | Button, link, or action shown |
K6. Data & Content Shown
| Field | Description |
|---|---|
| Screen | Screen name |
| Data fields | What data is displayed (column names, labels, values) |
| Content decisions | Specific text, placeholder values, sample data used |
K7. Visual Specifications (conditional — only if mock includes design details)
| Field | Description |
|---|---|
| Element | Component or area |
| Colors used | Actual hex/rgb values visible |
| Typography | Font sizes, weights visible |
| Spacing | Margins, padding visible |
visualVerification is falseRuns automatically when mock input #3 contains .html files. If no HTML mocks, skip to Phase 4.
Purpose: Render HTML mock files with Puppeteer and detect whether requirements (P1) and components (P3) from the PRD actually exist as visible elements in the rendered page. This is a presence check only — it answers "is this element in the DOM?" not "does it look correct?".
Combine PRD inventories into a checklist of elements to look for:
| Source | What to search for | Example |
|---|---|---|
| P3 (PRD Component Mentions) | Component names and their context | "search input", "data table", "filter dropdown" |
| P1 (Functional Requirements) | Key interaction surfaces | "export button", "date range picker" |
| P2 (Page/View Registry) | Page titles and landmarks | "Dashboard", "Settings" |
For each item, generate search heuristics:
role="search", role="table", role="navigation")<search>, <table>, <nav>, <dialog>, <form>)aria-label, data-testid, placeholder, name attributesFor each HTML mock file, execute a Puppeteer script that:
file:// protocol)networkidle0)display:none)visual-verification/{mock-filename}.pngvisual-verification/verification-results.jsonSee puppeteer-visual-verification.md for the script template.
Use the Puppeteer results to add a domVerified: true/false field to K2 (Visual Component Inventory) entries. For verified components, also record visible: true/false.
Add a visualVerification section to reconciliation-data.json containing:
{
"visualVerification": {
"enabled": true,
"mocksScanned": ["mock-dashboard.html", "mock-settings.html"],
"screenshots": ["visual-verification/mock-dashboard.png", "visual-verification/mock-settings.png"],
"checklist": [
{
"source": "P3",
"name": "search input",
"mockFile": "mock-dashboard.html",
"status": "found",
"selector": "input[type='search']",
"visible": true,
"boundingBox": { "x": 240, "y": 80, "width": 320, "height": 40 },
"uxComponentMatch": { "componentName": "SearchInput", "uxSection": "Section 3.2", "variants": ["default", "focused"] }
},
{
"source": "P1",
"name": "DataTable",
"mockFile": "mock-dashboard.html",
"status": "not_found",
"selectorsQueried": ["[role='table']", "[class*='table']", "table"],
"boundingBox": null,
"uxComponentMatch": null
}
],
"summary": {
"total": 24,
"found": 18,
"notFound": 6
}
}
}
How Phase 4 uses this data: When Phase 4C (PRD -> Mock) checks whether a component is present in the mock, it first checks visualVerification.checklist. A not_found status from Puppeteer is strong DOM-level evidence for a Coverage Gap finding. Include in the finding description: "Puppeteer verification: element not found in rendered HTML after querying [N] selectors."
After Puppeteer detection completes and before Phase 4, cross-reference each found element against the UX component registry (U3) to identify which UX component rendered it.
For each checklist item with status: "found":
Selector-to-component mapping — Parse the matched CSS selector and compare against U3 component names:
[class*="department-tile"] and U3 has a component named "DepartmentTile", that's a match.bar-target matching U3 component "BarChart" via shared prefix)Component-Page Matrix (U10) — If available, check which components U10 says should appear on the page that corresponds to this mock file. Prefer matches where U10 confirms the component belongs on this page.
Section reference — If the UX document uses numbered sections (e.g., "3.6 DepartmentTile"), record the section reference in uxSection.
Variants — If U3 or U4 defines variants for the matched component, record which variants are listed.
For each found checklist item, populate:
{
"uxComponentMatch": {
"componentName": "DepartmentTile",
"uxSection": "Section 3.6",
"variants": ["default", "selected", "empty"]
}
}
If no UX component match is found, set uxComponentMatch to null. This is not an error — it may indicate the Mock implements something the UX doesn't define (potential Q finding).
Run comparison checks based on input mode. Each check direction only runs if both source and target documents are present.
CRITICAL — Cross-phase independence rule:
docsTag.docsTag values = two different findings, even if the underlying PRD requirement is the same.A1. Requirement-level checks — For each PRD requirement (P1):
| Check | Finding if failed |
|---|---|
| Is the feature/page defined in UX (U5)? | Coverage Gap [PRD<>UX] |
| Are required components designed in UX (U3)? | Coverage Gap [PRD<>UX] |
| Are required states designed (U4)? | Coverage Gap [PRD<>UX] |
| Does UX define the same behavior PRD requires? | Conflict [PRD<>UX] |
| Do component/page names match? | Naming Drift [PRD<>UX] |
A2. Flow checks (if P5 and U11 both exist):
| Check | Finding if failed |
|---|---|
| Does UX navigation map cover all flow steps? | Coverage Gap [PRD<>UX] |
| Do flow step sequences match? | Conflict [PRD<>UX] |
A3. Page section checks (if P7 and U9 both exist):
| Check | Finding if failed |
|---|---|
| Is this section present in UX page composition? | Coverage Gap [PRD<>UX] |
| Do section contents match PRD expectations? | Conflict [PRD<>UX] |
A4. Component variant checks (if P3 mentions variants and U3 defines them):
| Check | Finding if failed |
|---|---|
| Does UX define all variants PRD references? | Coverage Gap [PRD<>UX] |
B1. Component/page checks — For each UX component (U3) and page (U5):
| Check | Finding if failed |
|---|---|
| Does this component map to a PRD requirement? | Scope Addition [PRD<>UX] |
| Does this page map to a PRD page/view? | Scope Addition [PRD<>UX] |
| Are there UX states with no PRD justification? | Scope Addition [PRD<>UX] |
| Are there interaction patterns not in PRD? | Scope Addition [PRD<>UX] |
B2. Page composition checks (if U9 exists):
| Check | Finding if failed |
|---|---|
| Does this section have PRD backing (P7 or P1)? | Scope Addition [PRD<>UX] |
B3. Navigation checks (if U11 exists):
| Check | Finding if failed |
|---|---|
| Does this navigation flow map to a PRD flow (P5)? | Scope Addition [PRD<>UX] |
Puppeteer enhancement: If Phase 3B ran, check visualVerification.checklist for each component. A not_found status is strong DOM-level evidence for a Coverage Gap. Include in the finding: "Puppeteer: element not found after querying [N] selectors."
Requirement-level checks — For each PRD requirement (P1):
| Check | Finding if failed |
|---|---|
| Is the feature/page represented in a mock screen (K1)? | Coverage Gap [PRD<>Mock] |
Are required components visually present (K2)? Use visualVerification.checklist if available. | Coverage Gap [PRD<>Mock] |
| Are required states shown (K4)? | Coverage Gap [PRD<>Mock] |
| Does the mock show behavior contradicting PRD? | Conflict [PRD<>Mock] |
| Do data fields match PRD requirements (K6 vs P1)? | Conflict [PRD<>Mock] |
Flow checks (if P5 and K5 both exist):
| Check | Finding if failed |
|---|---|
| Does mock navigation cover all flow steps? | Coverage Gap [PRD<>Mock] |
| Do flow step sequences match? | Conflict [PRD<>Mock] |
Screen/component checks — For each mock screen (K1) and component (K2):
| Check | Finding if failed |
|---|---|
| Does this screen map to a PRD page/view? | Scope Addition [PRD<>Mock] |
| Does this component map to a PRD requirement? | Scope Addition [PRD<>Mock] |
| Are there data fields shown with no PRD requirement? | Scope Addition [PRD<>Mock] |
Component alignment — For each UX component (U3) present in mock (K2):
| Check | Finding if failed |
|---|---|
| Does mock render the component as UX specifies? | Conflict [UX<>Mock] |
| Do variant choices match UX definitions? | Conflict [UX<>Mock] |
| Does mock follow UX state definitions? | Conflict [UX<>Mock] |
Layout alignment (if U9 and K3 both exist):
| Check | Finding if failed |
|---|---|
| Does mock layout match UX page composition? | Conflict [UX<>Mock] |
Visual spec alignment (if U1/U2 and K7 both exist):
| Check | Finding if failed |
|---|---|
| Do mock colors match UX design tokens? | Conflict [UX<>Mock] |
| Does mock typography match UX specs? | Conflict [UX<>Mock] |
Mock additions beyond UX:
| Check | Finding if failed |
|---|---|
| Does mock show components not in UX registry? | Scope Addition [UX<>Mock] |
| Does mock show states not in UX state definitions? | Scope Addition [UX<>Mock] |
For each requirement that appears in all three documents, trace the interpretation chain:
F1. Cascade violation check — PRD -> UX -> Mock:
| Check | Finding if failed |
|---|---|
| PRD says X, UX says Y (drift), Mock says Z (further drift) | Cascade Violation [PRD>UX>Mock] |
| Progressive interpretation: each document drifts further from PRD's original intent | Cascade Violation [PRD>UX>Mock] |
F2. Specificity gap check:
| Check | Finding if failed |
|---|---|
| UX invented details not present in PRD | Specificity Gap [PRD<>UX] |
| Mock invented details not present in UX | Specificity Gap [UX<>Mock] |
| Mock invented details not present in PRD | Specificity Gap [PRD<>Mock] |
| Check | Example |
|---|---|
| Contradictory requirements | FR-5 says "public access", FR-12 says "auth required" for same page |
| Undefined references | FR-8 references "admin dashboard" but no page defined |
| Ambiguous requirements | "The system should handle large datasets" — no threshold |
| Duplicate/overlapping FRs | FR-3 and FR-15 describe the same feature differently |
| Inconsistent terminology | Uses "Resource" and "Asset" interchangeably |
| Check | Example |
|---|---|
| Undefined tokens | Component references --accent but token not defined |
| Contradictory specs | Card says border-radius: 12px in one place, 8px in another |
| Missing states | Button component defines hover but not disabled |
| Incomplete responsive | Desktop defined, tablet/mobile not specified |
| Orphan components | Component defined but not placed on any page |
| Page composition gaps | Page lists a section but no components assigned |
| Navigation dead-ends | Page in navigation map has no outbound routes |
| Check | Example |
|---|---|
| Inconsistent components | Same component looks different across screens |
| Missing states | Error screen referenced in flow but not mocked |
| Orphan screens | Screen exists but unreachable from navigation |
| Data inconsistency | Same entity shows different fields on different screens |
| Visual inconsistency | Different colors/fonts for same element type across screens |
Build a requirement-level scorecard. For each requirement, assign a status and a reason explaining why it received that status:
| Status | Meaning |
|---|---|
| Aligned | PRD requirement fully covered in all provided documents, no conflicts |
| Partial | Covered in some documents but gaps remain |
| Conflict | Two or more documents contradict on this requirement |
| Gap | Missing from one or more target documents |
| N/A | Requirement doesn't need definition in target documents (backend, infrastructure) |
Status reason (mandatory for every requirement): A concise, human-readable explanation of why this requirement received its status. The reason must reference the specific documents and findings involved. Examples:
| Status | Example reason |
|---|---|
| Aligned | "Defined in PRD (FR-3), UX (SearchInput component with variants), and Mock (visible on Dashboard screen)" |
| Partial | "PRD defines date range filter (FR-7); UX has DatePicker component but Mock does not show it on any screen (coverage-gap-4)" |
| Conflict | "PRD says max 50 results per page (FR-12); UX specifies infinite scroll with no pagination (conflict-2)" |
| Gap | "PRD requires export to CSV (FR-15); not defined in UX or Mock (coverage-gap-8, coverage-gap-9)" |
| N/A | "Backend authentication requirement — no UI representation needed" |
The reason is stored in requirements[].reason in the JSON and displayed in the matrix and MD report.
Calculate per-document and overall scores:
This is the single source of truth for all visual outputs. Generate it before any other output file.
See data-schema.md for the complete JSON schema.
The JSON must include:
meta — mode, date, document names, file pathsscores — overall alignment, per-document coverage, per-document maturitystats — finding counts by category and severityrequirements — array of all PRD requirements with per-document status and a reason string explaining why each requirement has its statusfindings — array of all findings with ID, code, severity, docs tag, descriptions, quotesinventories — extracted inventories from each document (P1-P7, U1-U11, K1-K7)namingDrift — array of Naming Drift findings with terms per documentcascades — array of Cascade Violation findings with full 3-step chain (trilateral only)venn — pre-computed overlap counts for diagram generationgroups — feature area groupings for heatmap and treemapToken budget note: This file is compact JSON — far smaller than equivalent inline HTML. A 50-requirement, 30-finding audit produces ~15-25KB of JSON vs ~80-120KB of inline HTML.
See report-template.md for the complete structure.
Key sections:
All data comes from the already-generated reconciliation-data.json. Do not re-analyze — just format the JSON data into markdown.
See reference.md for the complete HTML/CSS/JS template.
CRITICAL: Do not inline any finding data into this file. Copy the HTML template from reference.md and ensure it loads data via:
fetch('./reconciliation-data.json')
.then(r => r.json())
.then(data => renderDashboard(data));
The template is a static shell with:
The HTML file size is constant (~25-30KB) regardless of whether the audit has 5 findings or 500. This prevents token exhaustion.
Interactive features (all driven by JSON data at runtime):
meta.modereason text explaining why it has its current status. Shown inline below the requirement title or in an expandable detail panel.Third tab in the dashboard. Shows internal consistency issues per document — findings that indicate a document contradicts itself.
Layout: One column per provided document (PRD, UX, Mock). Each column shows:
scores.health.prd, scores.health.ux, scores.health.mock.Data source: Filters findings[] where categoryKey is prd-internal, ux-internal, or mock-internal. Health scores from scores.health.
visualVerification is falseSee verification-map-template.md for the complete HTML/CSS/JS template.
CRITICAL: Same data-template separation pattern. This is a static HTML shell that loads reconciliation-data.json via fetch(). No inline data.
fetch('../reconciliation-data.json')
.then(r => r.json())
.then(data => init(data));
Complete coverage principle: Every requirement from requirements[] and every UX component from inventories.ux.U3 must appear in the UI. Nothing is omitted. Found elements get bounding boxes on screenshots; missing elements appear in the gaps/issues panel.
The template renders four integrated views:
Screenshot view (default) — One tab per mock screenshot with SVG bounding box overlays. Each box is color-coded by requirement status (green=aligned, amber=partial, red=conflict, blue=gap). Labels show both the FR ID and the matched UX component name for dual traceability. Clicking a box opens the detail panel.
List view — Table of ALL requirements (not just Puppeteer-verified ones) with columns: requirement ID + title, UX component match, reconciliation status, DOM status (found/not found/---), and matched selector. Every requirement in the reconciliation appears here.
Detail panel — Three sections per selected element:
Side panel tabs:
Summary header — Pill badges showing counts: aligned, partial, conflict, gap. Plus total requirements, found count, not-found count.
Filters — Status (aligned/partial/conflict/gap/na), DOM status (found/not found), UX component dropdown, mock file tabs.
Keyboard — 1/2/3/4 switch panel tabs, Esc clears selection, arrow keys navigate.
Output path: visual-verification/verification-map.html
generateDiagrams is falseOnly run this phase if the user opted in during Phase 0 step 6. If skipped, proceed directly to Phase 11.
See excalidraw-templates.md for the JSON structure templates.
Generate each file sequentially — do not attempt all four in a single output. Read the required data slice from reconciliation-data.json for each diagram.
Data source: requirements[] + scores.perDocument
Grid visualization:
groups[])meta.documents)Data source: venn object (pre-computed counts)
Overlap diagram:
Data source: requirements[] + findings[]
Flow diagram showing requirement traceability:
Data source: findings[] + groups[]
Treemap showing findings distribution:
reconciliation-data.json is valid JSON and parseablereconciliation-data.jsonstats object in JSON[PRD<>UX], etc.) are present on every findingreconciliation-data.json.[PRD<>Mock] that has Puppeteer evidence must include the Puppeteer result in the finding description. The visualVerification section in reconciliation-data.json must match the verification-results.json file.[PRD<>UX], verify that Phase 4C independently evaluated the same requirement against Mock. If Mock also has a gap or conflict, a separate finding with [PRD<>Mock] must exist. Conversely, for every [PRD<>Mock] finding, verify Phase 4A independently evaluated against UX. Flag any requirement that has a finding in one direction but was never evaluated in the other.verification-map.html exists in visual-verification/. Every checklist item with status: "found" must have a non-null boundingBox in reconciliation-data.json. The uxComponentMatch field must be populated for found items when UX document is provided (Phase 3B.5 ran).boundingBox must have positive width and height. Coordinates x and y must be non-negative. If any bounding box is invalid, log a warning but do not fail.Activated when input #4 (previous reconciliation folder) is provided. This phase enables incremental reconciliation — only new or changed requirements are re-analyzed, while unchanged requirements carry forward their previous results.
reconciliation-data.json from the previous reconciliation folder (not the MD report — the JSON is the structured source of truth)previousRequirements[] — all requirement objects with their statuses, reasons, and finding mappingspreviousFindings[] — all finding objects with IDs, codes, severities, descriptionspreviousScores — alignment scores and per-document coveragepreviousMeta — date, mode, document namesThe user specifies what changed. Accept any of these formats:
If the user does not specify what changed, ask once: "Which requirements or sections changed since the last run? (e.g., FR-12, FR-15, or 'Section 3 of the PRD'). Say 'all' for a full re-run with delta comparison."
Build the change set:
changedRequirementIds — explicit IDs the user listedchangedSections — PRD sections that were rewritten (map to requirement IDs by reading the new PRD)newRequirementIds — requirement IDs present in the current PRD but absent from previousRequirements[]removedRequirementIds — requirement IDs present in previousRequirements[] but absent from current PRDFor every requirement NOT in the change set:
previousRequirements[] into the current requirements[]previousFindings[] into the current findings[]"deltaStatus": "carried_forward" in the JSON outputDo NOT re-read source documents or re-analyze for carried-forward requirements. This saves significant context and tokens.
For requirements in the change set:
"deltaStatus": "new" or "deltaStatus": "changed""deltaStatus": "resolved"For newRequirementIds: Run full analysis (Phases 1-6). Mark as "deltaStatus": "new".
For removedRequirementIds: Do not include in current output. Record in delta summary as removed.
requirements[] arrayfindings[] arrayscores and stats from the merged datameta.deltaMode = true, meta.previousRun = "<previous folder path>", meta.changeSet = { changed: [...], new: [...], removed: [...] }Generate delta-summary.md with:
Also add delta section to reconciliation-data.json:
{
"delta": {
"previousRunDate": "2026-02-15",
"currentRunDate": "2026-03-06",
"scoresTrend": { "previous": 72, "current": 81 },
"carriedForward": 38,
"reAnalyzed": 7,
"newRequirements": ["FR-51", "FR-52"],
"removedRequirements": ["FR-10"],
"newFindings": ["conflict-31", "coverage-gap-45"],
"resolvedFindings": ["conflict-12", "coverage-gap-20"],
"changedFindings": ["conflict-5"],
"persistentFindingCount": 22
}
}
After merging, proceed to Phases 7-11 as normal using the merged data. The MD report and HTML dashboard show the complete current state (not just the delta). The delta summary is an additional output file.
reconciliation-data.json before any visual output. The HTML template is static and loads data at runtime via fetch(). Never inline finding data into HTML. This prevents output token exhaustion on large audits.reconciliation-data.json (not from scratch).reconciliation-data.json is the checkpoint. Once written, all analysis is persisted. If context runs out, the user starts a new session pointing to the JSON and only missing outputs are generated. Never re-read original documents in a resume session.npx claudepluginhub andershalo/halo-ai-dev-tools --plugin reconciliation-auditValidates project documentation: lints formatting and naming, checks broken/orphan links, verifies glossary terms and synonyms, detects contradictions/gaps, audits completeness via /doc:lint, /doc:links, etc.
Analyzes sphinx-needs projects for gaps, redundancies, inconsistencies in requirements traceability, orphans, status contradictions, and ID/schema validation.
Analytically scans a written artifact (spec, PRD, user stories) for blind spots: unstated assumptions, missing actors, failure modes, ambiguous terms, missing acceptance criteria, edge cases, and dependencies. Emits a categorized, severity-sorted shadow report.