clearwing-gap-analysis

name	clearwing-gap-analysis
description	This skill should be used when the user asks to "review plugin gaps", "audit each folder and file", "do a Clearwing-style gap analysis", "compare plugin structure maturity", or wants a per-folder and per-file structural review across one or more Obsidian plugin directories.
version	0.1.0

Clearwing-Style Gap Analysis

Use this skill to produce a structural gap review across one or more Obsidian plugin directories using a Clearwing-like artifact review style: explicit, folder-by-folder and file-by-file, with concrete gaps and recommended actions instead of generic summaries.

Purpose

Assess plugin maturity, ownership clarity, buildability, testability, and release readiness.

Focus on structural truth:

• What the directory appears to be
• Which files make it buildable and maintainable
• Which gaps prevent confident ownership or change
• Whether the root is a source repo, a release artifact, a mirror, or an archive

Do not default to line-level bug hunting. Treat this as repo topology and artifact hygiene analysis first.

When To Use

Use when the user asks for:

• A gap review across plugin folders
• A per-folder and per-file audit
• A Clearwing-style review
• Structural comparison across multiple plugin repos
• Identification of missing manifests, build configs, tests, docs, or release metadata
• Source-of-truth and duplication analysis

Core Review Model

Classify each target before judging it:

1. Determine repository role

• Source repo
• Monorepo with embedded plugin package
• Built distribution
• Vendor mirror or imported upstream
• Archive or holding area

2. Evaluate artifact completeness

• Plugin identity: manifest.json, plugin id, version metadata
• Build pipeline: package.json, tsconfig.json, bundler config
• Source surface: src/, typed entrypoints, submodule organization
• Test surface: unit, integration, e2e, fixtures
• Docs surface: README.md, specs, architecture notes, release notes
• Release surface: versions.json, version scripts, changelog, packaged artifacts

3. Evaluate operational clarity

• One clear source of truth per plugin id
• No ambiguous duplicates with overlapping manifests
• No committed transient state unless intentional
• No hidden nested repos unless intentional

4. Convert observations into gaps

• Missing artifact
• Ambiguous ownership
• Mixed source and build outputs
• Overgrown or under-documented surface
• Weak release discipline
• Weak test discipline

Workflow

Step 1: Inventory targets

Collect for each root:

• Top-level folders
• Canonical plugin files at root
• Presence of src/, tests/, docs/, scripts/, assets/
• Manifest id, version, minimum app version
• Package scripts and build tooling

Prefer fast structural commands such as Get-ChildItem, rg --files, and small JSON extraction from manifest.json and package.json.

Step 2: Detect duplicates and mirrors

Compare:

• Directory names that look like forks or variants
• Shared manifest.json ids
• Same plugin name with multiple roots
• Distribution-only roots that correspond to source roots elsewhere

If multiple roots map to one plugin id, call that out as a primary ownership gap.

Step 3: Classify maturity

Use practical buckets:

• distribution-only
• active-source-lightweight
• active-source-mature
• monorepo-plugin-subpackage
• archive-or-container
• ambiguous-duplicate

Do not penalize a distribution-only directory for lacking source if it is clearly documented as distribution-only. Penalize the ambiguity, not the absence.

Step 4: Write the review

For each plugin, write:

• A one-line classification
• Folder review
• File review
• Primary gaps
• Recommended action

Keep the review artifact-focused. Explain why a missing or duplicated file matters to maintainability.

Output Format

Use this shape:

## plugin-name
Classification: active-source-lightweight

Folder review:
- `src/` exists and is small enough to review quickly.
- No `tests/` or `e2e/` surface is present.
- No `docs/` tree beyond a root README.

File review:
- `manifest.json`, `package.json`, `tsconfig.json`, and bundler config are present.
- `versions.json` is missing, which weakens release compatibility tracking for Obsidian.
- Built `main.js` is committed beside source, which mixes source-of-truth and release output.

Primary gaps:
- Missing test surface.
- Weak release metadata.
- Mixed source and build artifacts in one root.

Recommended action:
- Decide whether the root is source-first or distribution-first.
- Add `versions.json` and a minimal smoke test path.
- Either document committed build artifacts as intentional or stop tracking them.

Review Priorities

Prioritize findings in this order:

1. Ownership ambiguity

• Duplicate roots
• Same manifest id in multiple directories
• Unclear canonical source tree

2. Missing buildability artifacts

• No package.json
• No bundler config
• No source for a repo that appears editable

3. Missing releaseability artifacts

• No versions.json
• No versioning path
• No changelog or release check in active repos

4. Missing testability artifacts

• No test scripts
• No fixture or smoke path in non-trivial repos

5. Documentation gaps

• No README
• No architecture notes in large repos
• No explanation for monorepo boundaries

Obsidian-Specific Heuristics

Treat these as strong signals:

• manifest.json present without source or build config: probably a compiled distribution
• versions.json missing in an active plugin repo: release discipline gap
• main.js committed beside src/: source/build mixing; acceptable only if intentional and documented
• Large src/ surface without docs: architecture discoverability gap
• node_modules/ committed: hygiene gap
• Nested .git/: mirror/import hygiene gap
• Multiple roots sharing the same plugin id: source-of-truth gap

Additional Resources

Reference Files

Use these references when writing the final report:

• references/report-template.md - Reusable report skeleton, classification set, and severity framing

Constraints

• Stay structural unless the user explicitly asks for code-level bug review.
• Avoid speculative judgments about product quality based only on file counts.
• Distinguish between a legitimate distribution directory and a broken source repo.
• Prefer concise, evidence-backed statements over broad cleanup advice.

Completion Standard

Finish when the output:

• Covers every requested plugin root
• Uses a consistent per-folder and per-file structure
• Identifies the highest-leverage gaps first
• Separates duplicate/ownership issues from ordinary missing files
• Ends with concrete recommended actions rather than vague hygiene notes