armelhbobdad/oh-my-skills / .claude/skills/skf-analyze-source
skf-analyze-source
VerifiedDiscover what to skill in a large repo and produce recommended skill briefs. Use when the user requests to "analyze source for skills" or "discover skill opportunities."
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.1 KB |
| assets/skill-brief-schema.md | markdown | 13.6 KB |
| customize.toml | config | 3.0 KB |
| references/auto-docs-only.md | markdown | 8.6 KB |
| references/continue.md | markdown | 2.0 KB |
| references/discover-additional-source.md | markdown | 11.0 KB |
| references/generate-briefs.md | markdown | 19.2 KB |
| references/headless-contract.md | markdown | 10.0 KB |
| references/health-check.md | markdown | 804 B |
| references/identify-units.md | markdown | 15.0 KB |
| references/init.md | markdown | 14.4 KB |
| references/map-and-detect.md | markdown | 16.4 KB |
| references/map-unit-exports.md | markdown | 6.2 KB |
| references/recommend.md | markdown | 9.0 KB |
| references/scan-project.md | markdown | 8.2 KB |
| references/scan-root.md | markdown | 3.1 KB |
| references/step-auto-scope-coexistence.md | markdown | 3.6 KB |
| references/step-auto-scope-corpora.md | markdown | 4.3 KB |
| references/step-auto-scope-split.md | markdown | 6.2 KB |
| references/step-auto-scope.md | markdown | 34.3 KB |
| references/step-shape-detect.md | markdown | 7.7 KB |
| references/unit-detection-heuristics.md | markdown | 11.8 KB |
| templates/analysis-report-template.md | markdown | 583 B |
references/recommend.md
View on GitHub---
nextStepFile: 'generate-briefs.md'
outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
schemaFile: 'assets/skill-brief-schema.md'
discoverFile: 'references/discover-additional-source.md'
advancedElicitationSkill: '/bmad-advanced-elicitation'
partyModeSkill: '/bmad-party-mode'
---
<!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
# Step 5: Recommend
## STEP GOAL:
To present each qualifying unit as a recommendation with evidence-based rationale, allow the user to confirm, reject, or modify each recommendation, and build the confirmed units list that drives brief generation.
## Rules
- This is the primary user decision point: every unit gets a decision before the run moves on, which a headless run takes by the §7 GATE default
- Present evidence for each recommendation, invite questions and pushback
## MANDATORY SEQUENCE
Every HARD HALT in this step names its exit code, `halt_reason` and phase. When `{headless_mode}` is true it first prints its envelope on stderr through the shared emitter (`{emitEnvelopeHelper}` and `{run_dir}` come from SKILL.md On Activation): stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "mode": "interactive", "report_path": "{outputFile as an absolute path}"}`, plus `"path"` when the halt names one, then run
```bash
uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
```
and display the line it prints verbatim. Write the payload as valid JSON: in the halt message and `path`, replace each backslash with / and each double quote with a backtick. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
### 1. Load Context
Read {outputFile} completely to obtain:
- Qualifying units from Identified Units, each with its project path (the deferred ones are listed in the summary, not given a card)
- Export map data per unit
- Integration points and coupling analysis
- Stack skill candidates from frontmatter
- Existing skills from frontmatter
- `intent_hint` from frontmatter (the goal the user stated at init; empty when none)
- `refs` from frontmatter: a unit's ref is its project path's entry there (none without one)
Load {schemaFile} for reference on what skill-brief.yaml requires (so recommendations are actionable).
**Apply `intent_hint` when ranking units.** If `intent_hint` is non-empty, use it to bias the order in which recommendation cards are presented and to soften the rationale for units that fall outside the stated intent (e.g., when `intent_hint` mentions "authentication and authorization", rank auth-related units first and flag unrelated units with a one-line rationale acknowledging the mismatch). If `intent_hint` is empty, present in the deterministic order from the export map.
### 2. Build Recommendation Cards
For each qualifying unit, prepare a recommendation card:
```
**Unit: {name}**
- Source: {its project path}{, at {its ref} when it has one}
- Path: {path}
- Language: {language}
- Boundary: {type} | Scope: {scope_type}
- Exports: {count} ({pattern})
- API Surface: {size}
- Integrations: imports from {list}, imported by {list}
- Coupling: {tight/loose/indirect}
- Confidence: {high/medium/low}
- Stack Skill: {yes — grouped with {units} / no}
- Status: {new / briefed: a brief from an earlier analysis at {its path}, rewritten if you confirm the unit / already-skilled → recommend update-skill}
**Rationale:** {2-3 sentences explaining WHY this should be a skill, citing specific detection signals and file paths}
**Proposed Brief Fields:**
- name: {the unit's name, as identify-units or map-and-detect derived it}
- scope.type: {full-library / specific-modules / public-api / component-library / reference-app / docs-only}
- scope.include: {suggested glob patterns}
- description: {suggested 1-3 sentence description, containing a literal `Use when` clause}
```
### 3. Present Recommendations
**Headless** (`{headless_mode}` true): no one answers the questions below. Take the §7 GATE default now (confirm every card as proposed and flag every stack skill candidate for create-stack-skill), record it as that GATE says, then continue at §6. No question of §3 to §5 is asked.
"**Recommendations for {project_name}**
I've analyzed {count} qualifying units. Here are my recommendations for skill creation:
---"
Present each recommendation card, then after ALL cards:
"---
**Summary:**
- **Recommended for new skills:** {count}
- **Already-skilled (recommend update-skill):** {count}
- **Stack skill candidates:** {count}
- **Deferred (outside the stated goal, not analyzed):** {count, with their names}
**For each unit above, please indicate:**
- **Y**: Confirm: generate skill-brief.yaml
- **N**: Reject: skip this unit
- **M**: Modify: adjust name, scope, or description before confirming
**Bulk shortcuts:**
- `all-Y`: confirm every recommendation as-is
- `all-N`: skip every recommendation
- Individual response list (e.g., `1:Y, 2:N, 3:M, ...`): explicit per-unit decisions (use this when you want to mix Y/N/M or modify any unit)
**Questions?** Ask 'why?' about any recommendation and I'll explain my reasoning with specific evidence."
### 4. Process User Decisions
Record a decision for every unit before moving on: Y adds it to `confirmed_units` with its proposed brief fields; N records the user's reason; M asks what to change (name, scope type, include patterns, description), applies it and confirms the result.
### 5. Confirm Stack Skill Candidates
If stack skill candidates were flagged, list them (units, detection signal, evidence): their units show strong co-integration patterns and may benefit from a consolidated stack skill via create-stack-skill. Ask "Flag these for create-stack-skill? (Y/N per candidate)" and record each decision.
### 6. Append to Report
Replace `[Appended by recommend]` in {outputFile} with:
- All recommendation cards (including rationale)
- User decisions per unit (confirmed/rejected/modified)
- Stack skill candidate decisions
Update {outputFile} frontmatter:
```yaml
confirmed_units: [{list of confirmed unit names}]
stack_skill_candidates: [{updated list with user decisions}]
```
A later pass through this section (after [A], [P] or [D], or in a session that resumed this step) replaces what the earlier one wrote. The step is marked complete only when [C] leaves it, so a run cancelled at the §7 menu resumes at these recommendations.
### 7. Present MENU OPTIONS
Lead with the decisions, so the menu is chosen against the final list:
"**Confirmed for brief generation:** {count}: {each confirmed unit with its final name, scope type and description}
**Rejected:** {count}: {each with its reason}
**Flagged for create-stack-skill:** {count}: {each grouping}"
Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Discover Additional Source [C] Continue to Brief Generation [X] Cancel and exit"
#### Menu Handling Logic:
- IF A: Invoke {advancedElicitationSkill}. For each unit what it surfaced changes, take the decision again as §4 says, redo §6, then redisplay this menu
- IF P: Invoke {partyModeSkill}, then handle what it surfaced as [A] does
- IF D: load, read the entire file, then execute {discoverFile} with the project path the user gives. It returns the new path's units with their export records and composite proposals. Present each proposal (accepted unless the user rejects it; an accepted one replaces its constituents as one unit and joins `confirmed_composites` in the frontmatter), build the cards of the new units (§2), take their decisions (§3 to §5), redo §6, then redisplay this menu
- IF C: update {outputFile} frontmatter (`stepsCompleted`: append `recommend`; `lastStep: 'recommend'`), then load, read the entire file, then execute {nextStepFile}
- IF X: HARD HALT (exit code 6, `halt_reason: "user-cancelled"`, phase `recommend:7`, with `unit_counts` reflecting the decisions made so far in its payload): "Cancelled at the recommendations."
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
**GATE [default: C]**: present the menu and wait for the user's choice. The default also answers every question of §3 to §5: confirm every card as proposed and flag every stack skill candidate. If `{headless_mode}`, §3 takes that default before any question and records it the moment it does: stage `{run_dir}/decision.json` as `{"gate": "recommend.recommendations", "default_action": "C", "taken_action": "C", "reason": "headless: auto-accept all recommendations and flag every stack skill candidate", "evidence": {"confirmed": [<each confirmed unit name>], "stack_skill_candidates": <the flagged candidate count>}}`, then run
```bash
uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
```
If the command fails, go on: only that entry is lost. At this menu a headless run continues with [C].
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |