skill-recommender

Purpose

Analyze user requests and recommend appropriate documentation skills from the AI Dev Flow framework catalog.

Problem Solved: Users must know which of 25+ skills to invoke for their documentation task, requiring deep framework knowledge.

Solution: Parse user intent, match against skill catalog, and provide ranked recommendations with confidence scores and rationale.

When to Use This Skill

Use skill-recommender when:

• User is unsure which skill to use for a documentation task
• Starting a new documentation workflow and need guidance
• Want to discover available skills for a specific intent
• Need help navigating the skill catalog

Do NOT use when:

• User explicitly requests a specific skill (e.g., "/skill doc-prd")
• Performing non-documentation tasks
• User is experienced and knows the target skill

Skill Inputs

Input	Type	Required	Description
user_request	string	Yes	Natural language description of what user wants to do
project_context	object	No	Project structure and existing artifacts (from context-analyzer)
max_recommendations	number	No	Maximum recommendations to return (default: 3)

Skill Workflow

Step 1: Parse User Intent

Extract action verbs and targets from the user request:

Intent Categories:

Category	Signal Keywords	Example Request
create	create, write, draft, new, add	"Create a new PRD for user authentication"
update	update, modify, edit, change, revise	"Update the traceability section of SPEC-01"
validate	validate, check, verify, audit, review	"Check if my artifacts have proper traceability"
analyze	analyze, review, examine, inspect	"Analyze the project documentation structure"
plan	plan, roadmap, schedule, organize	"Create an implementation roadmap from ADRs"

Target Extraction:

Target	Signal Keywords	Maps To
business requirements	business, brd, objectives	doc-brd
product requirements	product, prd, features, user stories	doc-prd
formal requirements	ears, formal, when-the-shall	doc-ears
test scenarios	bdd, tests, scenarios, gherkin	doc-bdd
architecture decisions	adr, architecture, decision	doc-adr
system requirements	sys, system, technical	doc-sys
requirements	req, requirement, atomic	doc-req
implementation plan	impl, implementation, plan	doc-impl
contracts	ctr, contract, api, interface	doc-ctr
specifications	spec, specification, yaml	doc-spec
tasks	tasks, todo, implementation tasks	doc-tasks
execution plans	iplan, execution, session	doc-iplan
traceability	trace, traceability, links	trace-check
validation	validate, quality, compliance	doc-validator
diagrams	diagram, mermaid, chart, flow	charts-flow, mermaid-gen
roadmap	roadmap, adr implementation	adr-roadmap
project management	mvp, mmp, release, planning	project-mngt

Step 2: Match Skills

Match parsed intent against skill catalog:

Skill Catalog (Core Documentation Skills):

Skill ID	Category	Layer	Description
doc-brd	core-workflow	1	Business Requirements Documents
doc-prd	core-workflow	2	Product Requirements Documents
doc-ears	core-workflow	3	EARS Formal Requirements
doc-bdd	core-workflow	4	BDD Test Scenarios
doc-adr	core-workflow	5	Architecture Decision Records
doc-sys	core-workflow	6	System Requirements
doc-req	core-workflow	7	Atomic Requirements
doc-impl	core-workflow	8	Implementation Plans (optional)
doc-ctr	core-workflow	9	API Contracts (optional)
doc-spec	core-workflow	10	Technical Specifications
doc-tasks	core-workflow	11	Implementation Tasks
doc-iplan	core-workflow	12	Execution Plans

Quality Assurance Skills:

Skill ID	Category	Description
trace-check	quality-assurance	Validate bidirectional traceability
doc-validator	quality-assurance	Validate documentation standards
code-review	quality-assurance	Code quality review
contract-tester	quality-assurance	Test API contracts

Utility Skills:

Skill ID	Category	Description
charts-flow	utility	Mermaid architecture diagrams
mermaid-gen	utility	Generate Mermaid diagrams
analytics-flow	utility	Analytics and data analysis
project-init	utility	Initialize project structure

Planning Skills:

Skill ID	Category	Description
adr-roadmap	planning	ADR implementation roadmaps
project-mngt	planning	MVP/MMP/MMR release planning
doc-flow	planning	SDD workflow orchestration

Step 3: Score and Rank

Calculate confidence scores based on:

Factor	Weight	Description
Intent match	40%	How well request matches skill intent signals
Target match	30%	Explicit skill/artifact type mentioned
Context fit	20%	Project state and workflow position
Usage patterns	10%	Common skill sequences

Confidence Levels:

• High (≥80%): Strong match, recommend with confidence
• Medium (50-79%): Good match, include alternative options
• Low (<50%): Weak match, suggest clarification

Step 4: Generate Recommendations

Format recommendations with rationale:

Output Format:

recommendations:
  - skill: doc-prd
    confidence: 92%
    rationale: "Request mentions 'product requirements' and 'features' - direct match for PRD creation"
    next_steps: "Run /skill doc-prd to create Product Requirements Document"

  - skill: doc-brd
    confidence: 65%
    rationale: "May need BRD first if business requirements not yet documented"
    condition: "Use if no BRD exists for this feature"

  - skill: doc-ears
    confidence: 45%
    rationale: "EARS follows PRD in workflow - consider after PRD completion"
    condition: "Use after PRD is complete"

clarification_needed: false
clarification_question: null

Example Usage

Example 1: Clear Intent

User Request: "I need to create a product requirements document for a new authentication feature"

Skill Analysis:

Intent: create (keywords: create, need)
Target: product requirements (keywords: product requirements document)
Domain: authentication feature

Recommendations:

recommendations:
  - skill: doc-prd
    confidence: 95%
    rationale: "Explicit request for Product Requirements Document"
    next_steps: "Run /skill doc-prd to create PRD for authentication feature"

  - skill: doc-brd
    confidence: 40%
    rationale: "BRD may be needed upstream if not already created"
    condition: "Check if BRD exists for authentication feature"

Example 2: Ambiguous Intent

User Request: "Help me document the system architecture"

Skill Analysis:

Intent: create (keywords: document)
Target: ambiguous - could be ADR, SYS, or diagrams

Recommendations:

recommendations:
  - skill: doc-adr
    confidence: 60%
    rationale: "Architecture decisions typically documented in ADRs"

  - skill: doc-sys
    confidence: 55%
    rationale: "System requirements capture technical architecture"

  - skill: charts-flow
    confidence: 50%
    rationale: "Architecture diagrams visualize system structure"

clarification_needed: true
clarification_question: "What aspect of architecture? (1) Decisions/rationale (ADR), (2) System specs (SYS), (3) Visual diagrams?"

Example 3: Validation Request

User Request: "Check if my documentation has proper links between artifacts"

Skill Analysis:

Intent: validate (keywords: check)
Target: traceability (keywords: links between artifacts)

Recommendations:

recommendations:
  - skill: trace-check
    confidence: 98%
    rationale: "Direct request for traceability validation"
    next_steps: "Run /skill trace-check to validate bidirectional links"

Integration with Other Skills

Integration	Description
context-analyzer	Receives project context for better recommendations
doc-flow	Can be invoked by doc-flow for skill discovery
workflow-optimizer	Shares workflow position awareness

Quality Gates

Definition of Done

• User request parsed successfully
• At least one skill recommendation provided
• Confidence scores calculated for all recommendations
• Rationale included for each recommendation
• Clarification question generated when ambiguous

Performance Targets

Metric	Target
Response latency	<500ms
Recommendation accuracy	≥85%
User acceptance rate	≥70%

Traceability

Required Tags:

@prd: PRD.000.001
@adr: ADR-000

Upstream Sources

Source	Type	Reference
PRD-00	Product Requirements	PRD-00
ADR-000	Architecture Decision	ADR-000

Downstream Artifacts

Artifact	Type	Reference
Selected doc-* skill	Skill Execution	Invoked based on recommendation

---

Version Information

Version: 1.0.0 Created: 2025-11-29 Status: Active Author: AI Dev Flow Framework Team