Skip to main content
skill CX Codex

03-shadow-areas — Claude Code skill: find gaps in documents

03-shadow-areas — a skill that scans written artifacts (ideas, user stories, PRDs, specs) and produces a structured report of blind spots—what the author has not addressed. Runs on Claude Code, Cursor, Codex, GitHub Copilot, and OpenCode.

MIT ★ 571 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add ai-driven-dev/framework
/plugin install aidd-refine@aidd-framework
Open on GitHub

What 03-shadow-areas does

03-shadow-areas analyzes text artifacts to surface gaps: missing requirements, unclear sections, insufficient detail. Each gap gets a category from a fixed taxonomy, a severity level (blocker, major, minor), and a direct question the author can act on immediately. It works as an analytical scanner, not as dialogue—one pass through the document and a ready report.

The skill has three actions: detect parses the artifact and extracts gaps, render-report formats them into markdown grouped by category and sorted by severity, and diff compares the current result against a prior report to show which gaps closed, which remain open, and which are newly found. Categories and severity rules live in references/locked-sets.json.

Use it when you need to find what is missing in a document before moving forward. This is not for interactive Q&A or code review—it targets written work.

What it helps with

  • surface gaps in a technical specification before development starts
  • verify a user story has enough detail
  • spot missing requirements in a PRD
  • track which gaps you closed in a revised document
  • flag the most critical omissions in a project idea

Example prompts for the agent

  • Scan spec.md for gaps and show a report grouped by category
  • Find blind spots in this user story text: [paste text]
  • Compare the new PRD version against the prior report in reports/prd-v1.md

How to install 03-shadow-areas

1Plugin marketplace

/plugin marketplace add ai-driven-dev/framework
/plugin install aidd-refine@aidd-framework

This installs the whole aidd-refine plugin with all its skills

2Skills CLI (Vercel)

npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a claude-code

3Manually: put the files in place

~/.claude/skills/03-shadow-areas/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/03-shadow-areas/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about 03-shadow-areas

How do I install 03-shadow-areas in Claude Code?

Run /plugin marketplace add ai-driven-dev/framework, then /plugin install aidd-refine@aidd-framework and npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a claude-code. The skill file goes to ~/.claude/skills/03-shadow-areas/SKILL.md.

What does 03-shadow-areas do?

It scans a document and produces a structured report of gaps: each omission gets a category, severity level, and a concrete question so the author knows what to clarify or fill in.

How do I install it in other IDEs?

For Cursor: npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a cursor. For Codex: npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a codex. For GitHub Copilot: gh skill install ai-driven-dev/framework 03-shadow-areas. For OpenCode: npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a opencode.

Source text

SKILL.md · MIT
---
name: 03-shadow-areas
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.
argument-hint: file | text
---

# 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

- `references/categories.md`: locked 7-category taxonomy with definition and example per category.
- `references/severity-rubric.md`: blocker / major / minor decision rules and examples.
- `references/probe-style.md`: direct-question form rules.
- `references/locked-sets.json`: machine-readable sets reused by the validator.

## Assets

- `assets/report-template.md`: report skeleton with header, per-category sections, and `status: clean` block.

© AI-Driven Dev · MIT · ai-driven-dev/framework

Similar skills

All skills for Writing and docs →

From the same set80

The whole set →
00-repo-init 00-repo-init prepares a fresh Git repository with a default branch, CONTRIBUTING.md, and a bootstrap commit, then pushes it to a remote host on request. CX Codex +1 ★ 571repo stars 09-for-sure The 09-for-sure skill runs an agent through repeated attempts until a runnable success check passes. Use it for work with a result that can be verified, such as a command. CX Codex +1 ★ 571repo stars 07-refactor 07-refactor rewrites code along one of four axes: performance, security, cleanup, architecture. It scans on its own or takes a finished audit report as the to-do list. CX Codex +1 ★ 571repo stars 00-init 00-init controls AIDD telemetry in projects: turns resource tracking on or off with consent, configures identity, or purges recorded metrics. CX Codex +1 ★ 571repo stars 11-explore 11-explore surveys a project along three axes: installed tooling, context and codebase. You get a compact map, then a deeper walk down whichever axis you name. CX Codex +1 ★ 571repo stars 04-audit 04-audit is a Claude Code skill that audits a codebase across seven quality pillars and produces a ranked report without changing code. CX Codex +1 ★ 571repo stars 01-bootstrap 01-bootstrap guides early SaaS architecture decisions and records them in aidd_docs/INSTALL.md. Use it while defining a new project’s stack and design. CX Codex +1 ★ 571repo stars checker checker — a subagent that judges finished work against a checklist, runs validation, and verifies the code serves the actual need. Reports findings with evidence, never edits. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open