/verify — Demonstrate Value, Find Gaps

Philosophy

"It builds" proves nothing. "Tests pass" proves nothing. The only proof that a feature works is running it on real data and showing visible results.

This skill is the adversarial self-audit: take what was planned, run it for real, and report what actually works vs. what was quietly skipped, stubbed, or broken.

Steps

1. Extract the Plan

Determine what was supposed to be delivered. Sources (in order):

• Active plan in conversation context
• Linear issue (extract from branch name, fetch with mcp__linear__get_issue)
• Task list (TaskList)
• _tasks/REG-XXX/plan.md if exists

Extract the concrete deliverables — not "add C++ support" but the specific capabilities the plan promised (e.g., "parser emits 75 JSON node types", "analyzer produces 30 node types", "resolver creates 12 edge types").

2. Choose a Demo Target

Pick a real project to run the new feature against. Priority:

1. Grafema itself — if the feature applies to its own codebase
2. Well-known open-source repo — clone a small, representative project from GitHub
3. Synthetic fixture — create a minimal but realistic file that exercises the feature

For language support tasks: create or find a file that covers the language's key constructs. Not a toy hello-world — something that exercises classes, functions, imports, templates/generics, error handling, etc.

For analysis/enrichment tasks: use an existing analyzed project and run the new capability against its graph.

3. Execute End-to-End

Run the full pipeline on the demo target. For each component in the plan, actually invoke it and capture output:

Parser (if applicable):

• Run the parser on a real source file
• Show the JSON AST output (or a representative sample)
• Verify: does the output cover the constructs present in the file?
• Count: how many of the planned node types actually appear?

Analyzer (if applicable):

• Feed the parser output to the analyzer
• Show the FileAnalysis output (nodes, edges, deferred refs)
• Count: how many of the planned node types / edge types are actually emitted?
• Verify: do semantic IDs look correct?

Resolver (if applicable):

• Feed the analysis output to the resolver
• Show the resolved edges
• Verify: do cross-file references actually resolve?

MCP tools / CLI (if applicable):

• Run the MCP query or CLI command
• Show the actual output
• Compare against what the user would expect

4. Planned vs. Actual Matrix

Build a concrete comparison table. This is the heart of /verify.

## Planned vs. Actual

| Planned Capability              | Status      | Evidence |
|--------------------------------------|-------------|----------|
| Parser: FunctionDecl nodes           | WORKS     | Seen in output for demo.cpp:10 |
| Parser: TemplateTypeParam nodes      | NOT TESTED  | No template in demo file |
| Parser: MacroExpansion nodes         | MISSING     | Macro present in file but not in output |
| Analyzer: CALL nodes from CallExpr   | WORKS     | 5 CALL nodes emitted |
| Analyzer: LAMBDA nodes               | STUBBED     | Handler exists but emits empty node |
| Resolver: EXTENDS edges              | WORKS     | MyDerived -> MyBase resolved |
| Resolver: virtual dispatch           | NOT TESTED  | Need polymorphic call site in fixture |

Status legend:

• WORKS — demonstrated on real data, output is correct
• NOT TESTED — demo target doesn't exercise this; need a better fixture
• MISSING — should be there but isn't; gap found
• STUBBED — code exists but produces empty/dummy output
• WRONG — produces output but it's incorrect
• DEFERRED — explicitly out of scope per plan (with justification)

5. Gap Drill-Down

For every MISSING, STUBBED, or WRONG item:

1. Locate the code that should handle this case
2. Diagnose: is it a missing handler? Wrong pattern match? Silent fallthrough?
3. Classify:
   • Quick fix (< 20 lines, obvious what to do) — fix it now
   • Needs investigation (root cause unclear) — describe the symptom
   • Design gap (feature not designed for this case) — note as limitation
4. Record in the report with specific file:line references

6. Produce the Report

## Verification Report: [Task ID / Title]

### Demo Target
[What was tested: file name, project, or fixture description]

### Value Demonstrated
[2-3 bullet points of what ACTUALLY works end-to-end, with real output snippets]

### Planned vs. Actual
[The matrix from Step 4]

### Gaps Found
[For each MISSING/STUBBED/WRONG item:]
- **[item]**: [diagnosis] — [file:line] — [quick fix | needs investigation | design gap]

### Deferred (per plan)
- [item]: [reason]

### Verdict: [DELIVERS VALUE | PARTIAL VALUE | NO VALUE YET]

### Recommended Next Steps
[Prioritized list of what to do next to close gaps]

7. Fix Quick Wins (Optional)

If there are quick fixes (< 20 lines each) and fewer than 5 of them — fix them now and re-run the demo to update the report. Don't ask for permission on trivial fixes that close real gaps.

For larger fixes — leave them as "Recommended Next Steps" in the report.

---

Choosing Good Demo Targets

For language support (parser/analyzer/resolver)

Create a single file that covers the breadth of the language. Checklist:

• Function/method declarations (various signatures)
• Class/struct/type definitions
• Inheritance / interfaces / traits
• Imports / includes / modules
• Generics / templates
• Lambdas / closures
• Error handling (try/catch/throw)
• Control flow (if/for/while/switch)
• Variable declarations (various storage classes)
• Calls (free function, method, static, constructor)

For analysis features

Use the Grafema codebase itself via MCP tools — it's always available and already analyzed.

For enrichment / resolver features

Run grafema analyze on a small open-source project, then query the graph for the new edge types / enrichments.

---

Anti-Patterns

• Declaring victory from line counts — "6741 lines created" means nothing if the lines don't produce correct output
• Demo on trivial input — "hello world" parsing proves nothing; use realistic code
• Skipping the matrix — the planned-vs-actual table is mandatory, not optional
• "It should work because it follows the pattern" — run it and see
• Hiding NOT TESTED behind "out of scope" — if the plan said it, it's in scope; if you can't test it, say NOT TESTED, not DEFERRED
• Fixing gaps silently — if you find and fix gaps, report them as "gap found and fixed", not as if they never existed