Compare user expectations (UTCs) with code reality to identify gaps. Use when you need to understand discrepancies between what users expect and what code actually does.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
analyzing-gaps
description
Compare user expectations (UTCs) with code reality to identify gaps. Use when you need to understand discrepancies between what users expect and what code actually does.
user-invocable
true
allowed-tools
Read, Write, Glob, Grep, Edit
Analyzing Gaps
Compare user expectations captured in UTCs and journeys with actual code behavior documented in reality files. Generate structured gap reports with severity classification, JTBD impact mapping, and resolution recommendations.
Gap analysis compares user expectations (from canvases) with code behavior (from reality files). The failure modes arise when either input is wrong — producing phantom gaps that don't exist, or missing real gaps because the comparison baseline is outdated.
Target (Correct Behavior)
The skill loads a journey definition, reads the linked canvases to extract user expectations (Level 3 hypotheses, expectation gaps, journey fragments), then loads the corresponding reality file from /ground to get actual code behavior. For each expectation, it checks whether the code supports, partially supports, or does not support the expected behavior. Gaps are classified by type (Bug, Feature, Discoverability) and severity.
A gap exists only when there is a verifiable mismatch between what the user expects (grounded in their quotes and behavior) and what the code actually does (grounded in the reality file). Both sides must be grounded — hypothesis vs. hypothesis is not a gap, it's speculation.
Near Miss — Concept Impermanence
The seductively wrong behavior: using a stale reality file as the code-side ground truth.
Reality files are point-in-time snapshots generated by /ground or /ride. Code changes continuously — a bug fix merged yesterday may have closed a gap that the reality file still shows as open. Running gap analysis against a week-old reality file produces false positives: gaps that were real when the reality was captured but no longer exist.
The staleness risk compounds with canvas data:
Canvas says user expected X (captured 3 weeks ago)
Reality file says code does Y (captured 2 weeks ago)
Code was updated to do X (merged 1 week ago)
Gap analysis reports X ≠ Y → false gap
The correct behavior: check reality file freshness before analysis. If the reality file is older than the most recent commit touching the relevant code paths, warn the operator and suggest re-running /ground. Never report a gap with HIGH confidence from stale inputs — downgrade to MEDIUM with a staleness note.
The /drift skill exists precisely for this purpose — it computes confidence decay on artifacts. Gap analysis should consume drift scores, not ignore them.
Category Error — Coupling Inversion
The fundamentally wrong behavior: treating every code change in a relevant file as evidence of a gap.
A code change is not a gap. A gap is a mismatch between user expectation and code behavior. When /ground generates a new reality file showing a function was refactored, that refactoring is only a gap if it changed behavior that users depend on. Internal refactoring (same behavior, different implementation) produces a diff in the reality file but zero user-facing impact.
The inversion: the skill should flow from user expectations → code behavior check. Not from code changes → user impact speculation. Starting from code changes and guessing which users might be affected reverses the Observer's research direction — it turns hypothesis-first research into code-first speculation.
Examples of this inversion:
"Score calculation function was refactored" → not a gap unless scores actually changed
"New API endpoint added" → not a gap, it's a feature (users can't expect what didn't exist)
"CSS class renamed" → not a gap unless visual output changed
The skill should only report gaps where a specific user expectation (quoted, attributed, from a canvas) does not match a specific code behavior (verified, from a fresh reality file). Everything else is noise.
A concrete scenario: the score-api team refactors the calculateOGScore() function — extracting helper methods, renaming internal variables, improving test coverage. The reality file diff shows 200 lines changed. But the function's inputs and outputs are identical. Gap analysis that starts from "200 lines changed in scoring" and speculates about user impact will generate false gaps for every canvas that mentions OG scores.
The correct sequence:
Load canvas expectation: "User expected OG score to reflect recent mints"
Check reality file: Does calculateOGScore() include recent mints? → Yes (unchanged behavior)
Result: No gap. The refactoring is invisible to the user.
Starting from the code diff inverts this: "200 lines changed → which users might be affected? → anyone who mentioned OG scores." This produces a gap report full of false positives that wastes the operator's time triaging non-issues.
The /drift skill provides the necessary freshness signal. If the reality file's confidence has decayed below the threshold, gap analysis should either refuse to run (with a suggestion to re-ground) or downgrade all reported gaps to LOW confidence with a staleness warning. High-confidence gaps from stale inputs are worse than no gaps at all — they create false certainty.
Error Handling
Error
Resolution
Journey not found
List available journeys, suggest creation
No source canvases
Prompt to add canvases to journey
Reality file not found
Suggest running /ground first
No gaps found
Report success, mark journey as aligned
Canvas parse error
Log error, continue with available canvases
Integration Points
grounding-code: Reality files as input
observing-users: UTCs as input
shaping-journeys: Journeys as input
file-gap: Gap reports drive issue creation
diagramming-states: Gap indicators in dual diagrams
walking-through: Gaps inform test focus areas
Related
/ground - Create reality files from code
/file-gap - Create issues from gaps
/diagram --with-reality - Visualize gaps in diagrams
/walkthrough - Verify gaps through interactive testing
