Name: feature-enhance

Description:

Comprehensive feature-enhancement discovery skill. Points at any codebase — the current
Claude Code workspace, a local source folder, or a Forgejo/Git repo URL — scans the full
stack, inventories existing features, surfaces incomplete/stub work, then researches
comparable apps and platforms to generate a prioritized list of value-add enhancements.
Outputs a structured FEATURE_ENHANCEMENTS.md report.
---
Trigger whenever the user says: "feature enhancement", "what features are we missing",
"analyze my codebase for improvements", "compare to competitors", "what should I add next",
"audit my app", "run the enhancement skill", "scan for TODOs and features", "what else
should this do", or points at a project and asks for improvement ideas. Also triggers when
user wants to know how their app stacks up against similar tools or what features
competitors have that they don't.
---

# Feature Enhancement Skill

Scans a codebase, inventories its stack and current feature surface, identifies incomplete
work, and then uses web research to surface prioritized feature enhancements drawn from
comparable real-world products.

Output: FEATURE_ENHANCEMENTS.md in the project root (or a specified output dir).

---

## When to Use

- User wants to know what features their app is missing

• User wants a competitive analysis relative to their project domain
  
• User wants to inventory existing features + find TODOs/stubs
  
• User wants a research-backed feature roadmap
  
• Before starting a new sprint or planning cycle
  
• After inheriting or onboarding to an existing codebase

## When NOT to Use

- Single-file scripts or CLI tools with no feature surface — just answer directly

• User wants UI improvements (use the design-loop skill instead)
  
• User wants a new project scaffolded from scratch (use brainstorming skill)

---

## Workflow

### Phase 0 — Resolve Target

Determine what to scan. Ask if not specified:

``<br />

1. Current Claude Code workspace → use . (cwd)<br />
2. Local path → use the provided path<br />
3. Forgejo/Git URL → pass --forgejo-url to discover.py<br />

`</p> <p>If the user provides a Forgejo/Git URL, extract it and pass it directly to discover.py.<br /> The script handles cloning automatically.</p> <p>Confirm before proceeding:<br /> &gt; "Scanning {resolved_path} — is that the right target?"</p> <p>---</p> <p>### Phase 1 — Run Discovery</p> <p>`bash<br />

Determine the skill directory (where this SKILL.md lives)<br />

SKILL_DIR="$(dirname "$(realpath "$0")")" # or resolve from context</p> <p># Set output dir — default to project root or a fe-output subdirectory<br /> OUTPUT_DIR="{target_path}/fe-output"<br /> mkdir -p "$OUTPUT_DIR"</p> <p># Run the discovery script<br /> python "{SKILL_DIR}/scripts/discover.py" {target_path} \<br /> [--forgejo-url {url_if_provided}] \<br /> --output "$OUTPUT_DIR/context.json"<br /> `</p> <p>After running, read context.json and surface a concise discovery summary to the user<br /> before proceeding:</p> <p>`<br /> 📦 Project: {project_name} ({domain})<br /> 🧩 Frameworks: {frameworks}<br /> 🗄️ Databases: {databases}<br /> 🔐 Auth: {auth_tools}<br /> 📄 Routes/Pages: {total_routes}<br /> 🧱 Components: {total_components}<br /> 🚧 Stubs/TODOs: {total_stubs}<br /> 🐍 Empty Functions: {total_empty_fns}<br /> `</p> <p>Ask: "Does this look right? Anything to correct before I do the research phase?"</p> <p>---</p> <p>### Phase 2 — Web Research</p> <p>Using the detected domain from context.json:</p> <p>1. Load the comparables list from data/app_types.json for the detected domain.<br /> If domain not found, fall back to "web-app".</p> <p>2. Run the following searches (use your web_search tool):<br />

• The 2-3 search_queries for the detected domain<br />
• For each of the top 3-4 comparable apps: "{app_name} features 2025"<br />
• "{domain} SaaS best practices features 2025" (or equivalent)<br />
• "what features should a {domain} app have"</p>

<p>3. For each notable competitor, fetch its features page or about page if a URL is<br /> readily available in search results. Use web_fetch if needed.</p> <p>4. Assemble research.json — write it to $OUTPUT_DIR/research.json.<br /> Strict format (see schema below). This file is what generate_report.py consumes.</p> <p>research.json Schema:<br /> `json<br /> {<br /> "domain": "sports-pool",<br /> "searched_at": "2026-04-20T14:30:00",<br /> "competitors": [<br /> {<br /> "name": "ESPN Fantasy Pick'em",<br /> "url": "https://fantasy.espn.com",<br /> "description": "One-line description of what it is.",<br /> "notable_features": [<br /> "Feature A",<br /> "Feature B"<br /> ],<br /> "differentiators": [<br /> "What makes it stand out vs. generic options"<br /> ]<br /> }<br /> ],<br /> "enhancements": [<br /> {<br /> "title": "Real-time Score Updates",<br /> "priority": "high",<br /> "effort": "medium",<br /> "category": "Live Data",<br /> "description": "Paragraph describing the enhancement in detail.",<br /> "rationale": "Why this matters for the specific domain/user base.",<br /> "implementation_notes": [<br /> "Use WebSockets or SSE for live push",<br /> "Integrate with The Odds API or ESPN API",<br /> "Consider fallback polling if WebSocket not supported"<br /> ],<br /> "seen_in": ["ESPN Fantasy", "Sleeper", "DraftKings"]<br /> }<br /> ]<br /> }<br /> `</p> <p>Priority values: critical, high, medium, low<br /> Effort values: small, medium, large, xl</p> <p>&gt; ⚠️ Aim for 8–15 well-researched enhancements. Quality over quantity.<br /> &gt; Each enhancement should be specific to THIS project's domain and detected stack,<br /> &gt; not generic advice.</p> <p>Tailor enhancements to the actual stack. For example:<br />

• If Next.js detected → suggest App Router patterns, RSC, streaming<br />
• If Supabase detected → suggest Row Level Security, Realtime subscriptions<br />
• If stubs detected → call out "Finish X stub feature" as a high-value quick win</p>

<p>---</p> <p>### Phase 3 — Generate Report</p> <p>`bash<br /> python "{SKILL_DIR}/scripts/generate_report.py" \<br /> "$OUTPUT_DIR/context.json" \<br /> "$OUTPUT_DIR/research.json" \<br /> --output "{target_path}/FEATURE_ENHANCEMENTS.md"<br /> `</p> <p>After generating:<br />

• Read the report file<br />
• Present it to the user with present_files if available<br />
• Give a brief spoken summary of the top 3 recommendations</p>

<p>---</p> <p>### Phase 4 — Interactive Drill-Down (optional)</p> <p>After delivering the report, offer:</p> <p>`<br /> What would you like to do next?</p> <p>A) 🔬 Deep-dive on a specific enhancement (full implementation plan)<br /> B) 🎯 Filter by priority or effort level<br /> C) 🔄 Re-scan after making changes<br /> D) 📋 Export the matrix as a Todoist task list<br /> E) 🏗️ Scaffold the top enhancement right now<br /> `</p> <p>If the user picks D, format enhancements as Todoist tasks and add them via the<br /> Todoist MCP if connected.</p> <p>If the user picks E, use the brainstorming skill or senior-frontend skill<br /> depending on what the top enhancement is.</p> <p>---</p> <p>## File Layout</p> <p>`<br /> feature-enhance/<br /> ├── SKILL.md ← this file<br /> ├── scripts/<br /> │ ├── discover.py ← Phase 1: deep codebase scanner → context.json<br /> │ └── generate_report.py ← Phase 3: assembles FEATURE_ENHANCEMENTS.md<br /> └── data/<br /> └── app_types.json ← domain → comparables + search queries<br /> `</p> <p>Output files (written to {target}/fe-output/):<br /> `<br /> fe-output/<br /> ├── context.json ← raw discovery data<br /> └── research.json ← Claude-assembled competitor/enhancement data<br /> FEATURE_ENHANCEMENTS.md ← final report (in project root)<br /> `</p> <p>---</p> <p>## Edge Cases</p> <p>| Situation | How to Handle |<br /> |-----------|--------------|<br /> | Forgejo URL requires auth token | Ask the user for a personal access token; use GIT_TOKEN env or git clone https://token@url |<br /> | Monorepo (multiple apps) | discover.py will detect multiple package.json files; ask user which sub-app to target |<br /> | Very large codebase (50k+ files) | discover.py caps stubs at 500 and routes at 200 — mention this in the summary |<br /> | Domain not in app_types.json | Fall back to "web-app" key; note the fallback to the user |<br /> | No internet access | Skip research phase; generate report with context only and note the gap |<br /> | discover.py fails (bad encoding, etc.) | Surface the error, offer to proceed with manual stack description from the user |</p> <p>---</p> <p>## Tips for Best Results</p> <p>- Run from inside the project root whenever possible — this gives discover.py the<br /> cleanest signal without needing explicit path arguments.<br />

• For Forgejo repos, use the full clone URL including .git suffix.<br />
• The research phase is where the real value is — let it run a solid 4-6 web searches<br />

before writing research.json. Don't rush it with just 1-2 queries.<br />

• Stack specificity matters — enhancements that reference the actual detected frameworks<br />

(Next.js App Router, Supabase Realtime, Prisma schema extensions, etc.) are far more<br /> actionable than generic web app advice.<br />

• If the user's Forgejo instance is forgejo.fmrdigital.dev (or similar internal host),<br />

the clone may need to run with GIT_SSL_NO_VERIFY=1` if using a self-signed cert.