learning-a-tool

name	learning-a-tool
description	Create learning paths for programming tools and libraries. Use when user asks to learn, understand, or get started with any standalone programming tool or library (e.g., ripgrep, pdfplumber, pytest, Redis). NOT for full frameworks — use learning-a-framework for those.

Learning a Tool

Create comprehensive learning paths for programming tools.

Workflow

Phase 1: Research

Gather information from three sources. Research each source independently, then aggregate findings.

From Official Documentation (docs_researcher)

• Official docs URL and current version
• The motivation behind the tool
• What problem does it solve / what does it help with
• What types of applications can be built using the tool
• Use cases
• Installation steps and prerequisites
• Core concepts (3-5 fundamental ideas)
• Official code examples
• Getting started or tutorial content
• API reference highlights
• Known limitations or caveats

From the Repository (repo_analyzer)

• Repository URL and metadata (stars, last commit, license)
• Core system architecture (configuration, data processing flow, ...)
• README quick start section
• Examples folder contents (what each example demonstrates)
• Concise summary of the project's main function and the technologies used

From Community Content (web_researcher)

• Top tutorials (title, author, URL, why it's valuable)
• Video resources (title, channel, duration)
• Comparison articles (vs alternatives, key tradeoffs)
• Common gotchas and mistakes people mention
• Community channels (Discord, Reddit, forums)
• Real-world use cases and testimonials

Practical Articles Research (web_researcher — separate search)

Run a dedicated second search specifically targeting practitioner-oriented content. Use queries like "practical tips for {tool}", "{tool} best practices", "{tool} common mistakes", "{tool} recommended workflow".

Look for:

• Essential configuration tips and recommended defaults
• Common mistakes and anti-patterns practitioners have documented
• Performance optimization tips and benchmarks
• Useful plugins, extensions, or complementary tools
• Debugging techniques and troubleshooting playbooks
• Recommended workflows from experienced users

Phase 2: Structure

Organize content into progressive levels. references/progressive-learning.md is the source of truth.

You MUST create exactly 5 levels in this order:

1. Level 1: Overview & Motivation
2. Level 2: Installation & Hello World
3. Level 3: Core Concepts
4. Level 4: Practical Patterns
5. Level 5: Next Steps

Do NOT merge, skip, or rename levels. The level names above are FINAL — use them exactly. The reference file provides depth and content guidelines only, not level names.

Phase 3: Output

Generate the learning path folder.

Output Format

Create the folder in the current working directory (./research_output/learning-{tool-name}/) containing:

research_output/learning-{tool-name}/
├── README.md           # Overview, essential references, and how to use this learning path
├── resources.md        # All links organized by source (official, community)
├── learning-path.md    # Main content following the five levels
├── practical-takeaways.md # Actionable advice sourced from practitioner articles
└── code-examples/      # Runnable code for each section
    ├── 01-hello-world/
    ├── 02-core-concepts/
    └── 03-patterns/

README.md Must Include an "Essential References" Section

After the overview and before the learning path description, include a curated Essential References section with the 5-8 most important links a learner should bookmark:

• Official docs — main documentation URL
• Repository — GitHub URL with star count
• Best tutorial — single best written tutorial with author name
• Best video — single best video resource with channel and duration
• Community — primary community channel (Slack, Discord, or Reddit)
• Changelog/Releases — where to track updates

Format as a markdown table:

Resource	Link	Why
Official Docs	docs.example.com	Comprehensive reference, always up-to-date
...	...	...

practical-takeaways.md Guidelines

This file distills practitioner wisdom into immediately actionable content. It should be sourced primarily from the dedicated practical articles research, NOT rehashed from learning-path.md. Structure it with sections like:

• Recommended Workflow — step-by-step workflow from experienced users
• Essential Configuration — must-have settings, dotfiles, and config snippets
• Common Mistakes — anti-patterns and pitfalls practitioners have documented
• Performance Tips — optimization techniques and benchmarks
• Useful Plugins & Extensions — community-recommended add-ons with install commands
• Debugging Playbook — common issues and how to diagnose them

Include code snippets, config examples, and checklists where the source material supports them.