learnings-researcher_skill

Overview

This skill searches the docs/solutions/ knowledge base to surface past solutions, patterns, and gotchas before you start new work. It focuses on frontmatter metadata (tags, module, component, symptoms) to quickly find highly relevant institutional learnings. The goal is to prevent repeated mistakes and speed planning by returning concise, actionable summaries.

How this skill works

First, it extracts keywords from your feature or bug description (modules, technical terms, symptoms, components). It then runs parallel Grep-style frontmatter filters across docs/solutions/ to produce a small candidate set. For candidates it reads only frontmatter, scores relevance, and fully reads only the strong matches to extract distilled summaries and prevention guidance. It always checks a critical-patterns file for organization-wide must-know issues.

When to use it

• Before implementing a feature touching existing systems (avoid repeating mistakes)
• When planning a fix for a bug or performance regression
• During architecture or design reviews to surface prior solutions
• When onboarding to a code area with existing documented patterns
• Before making database, integration, or security changes

Best practices

• Start by extracting modules, symptoms, and synonyms from the task description
• Narrow by category directory when feature type is clear (performance, database, security)
• Run multiple Grep filters in parallel and include title:, tags:, and module: patterns
• Limit reads to frontmatter for candidates; fully read only strong/moderate matches
• Always read the critical-patterns file regardless of candidate results
• If >25 candidates, re-run with more specific patterns; if <3, run a broader content grep

Example use cases

• Adding email threading: search for module: BriefSystem, component: email_processing, tags: email/mail
• Debugging a slow API: narrow to performance-issues and grep for N+1, caching, timeout
• Database migration: search database-issues for missing_index or missing_association warnings
• Fixing intermittent job failures: grep background_job, async_timing, thread_violation
• Security review: restrict search to security-issues and match tags like auth, permission