# 03 Shadow Areas

Scan a markdown artifact (idea, stories, PRD, spec) for blind spots into a shadow...

- Repository: https://github.com/ai-driven-dev/framework (542 stars)
- Category: Git and review
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ai-driven-dev/framework --skill 03-shadow-areas -g -a claude-code -y`
Codex: `npx skills add ai-driven-dev/framework --skill 03-shadow-areas -g -a codex -y`
Cursor: `npx skills add ai-driven-dev/framework --skill 03-shadow-areas -g -a cursor -y`
Gemini CLI: `npx skills add ai-driven-dev/framework --skill 03-shadow-areas -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add ai-driven-dev/framework`

## Description

Scan a markdown artifact (idea, stories, PRD, spec) for blind spots into a shadow report grouped by category and severity. Use to find gaps or what is missing in a written artifact. Not for interactive Q&A or code review.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Shadow Areas

Analytically scans a written artifact for gaps the author has not addressed. Unlike iterative Q&A clarification, this skill reads the existing material and emits a structured report: each gap carries a category from a locked 7-category taxonomy, a 3-tier severity, and a direct-question probe the author can act on immediately.

## Actions

| #   | Action           | Role                                                                     | Input                                    |
| --- | ---------------- | ------------------------------------------------------------------------ | ---------------------------------------- |
| 01  | `detect`         | Parse input, extract gaps, classify category and severity, emit probes   | file path or inline text                 |
| 02  | `render-report`  | Render markdown grouped by category and sorted by severity, write report | gap list from detect                     |
| 03  | `diff`           | Load prior report, classify gaps as closed / still-open / newly-introduced | gap list from detect + prior report path |

Dispatch by context: with no prior report run `detect` then `render-report`; with one, run `detect` then `diff`.
Before running an action, read its file in `actions/`, not only the table or assets.

## Transversal rules

- Never modify the source artifact.
- Every gap carries all three: a category, a severity, and a probe question.
- Every probe is a direct question ending with `?`.
- Categories and severities come from the locked sets in `references/locked-sets.json`.
- When zero blockers and zero majors remain, stamp the report `status: clean`.
- On re-runs, gaps are matched by category and snippet, never by question wording, so rephrasing a question never creates a spurious "newly introduced" gap.

## References

The rest: https://github.com/ai-driven-dev/framework/blob/HEAD/plugins/aidd-refine/skills/03-shadow-areas/SKILL.md