tech-research

name	tech-research
description	Deep-researches a technology topic and caches knowledge. Use when the knowledge cache has no fresh entry for a technology needed for the current task.
user_invocable	true
argument	The technology/framework/library to research (e.g., "Entity Framework Core", "React 19", "Swift Concurrency")

Tech Research Skill

You are researching a technology topic and caching the results for future use. Follow these steps precisely.

Step 0 — Ensure repo exists

Check if ~/Developer/github/gordonbeeming/learning-agent/ exists. If not, clone it:

git clone [e-mail]:gordonbeeming/learning-agent.git ~/Developer/github/gordonbeeming/learning-agent

Also pull latest changes:

cd ~/Developer/github/gordonbeeming/learning-agent && git pull --rebase

Step 1 — Normalize the topic to a slug

Convert the argument to a kebab-case slug:

• Lowercase everything
• .NET → dotnet, C# → csharp, C++ → cpp
• Spaces and special characters → hyphens
• Collapse consecutive hyphens
• Max 60 characters

Examples:

• "Entity Framework Core" → entity-framework-core
• "React 19" → react-19
• ".NET 10" → dotnet-10
• "Swift Concurrency" → swift-concurrency
• "C# 13" → csharp-13

Step 2 — Check cache

Read ~/Developer/github/gordonbeeming/learning-agent/index.json.

Look for the slug in the topics object. If found, compare the expiresAt value to today's date.

Read ~/Developer/github/gordonbeeming/learning-agent/config.json for the stalenessDays value (used when creating new entries).

Step 3 — Cache hit (fresh)

If the topic exists and expiresAt is in the future:

1. Read ~/Developer/github/gordonbeeming/learning-agent/<summaryPath> (from the index entry)
2. Output the summary content to the user
3. Done — do NOT re-research

Step 4 — Cache miss or stale

If the topic is missing or expiresAt is in the past, spawn a research subagent.

Use the Agent tool to spawn an isolated research subagent with subagent_type "general-purpose". Give it this prompt:

You are a technology research agent. Research the following technology thoroughly and produce two outputs.

Technology to research: [THE TOPIC]

## Research Instructions

Use these tools to gather information:

1. **context7 MCP** (primary source): First call `resolve-library-id` with the technology name to find the library ID. Then call `query-docs` with that library ID to get current documentation. If the technology has multiple relevant libraries, resolve and query each one.

2. **WebSearch**: Search for:
   - "[technology] official documentation [current year]"
   - "[technology] best practices [current year]"
   - "[technology] breaking changes latest version"
   - "[technology] common pitfalls"
   - "[technology] migration guide" (if applicable)

3. **WebFetch**: Fetch specific documentation pages found via search results.

## Required Output Format

Produce EXACTLY two sections, clearly delimited:

### ===SUMMARY_START===

Write a concise summary (800-1500 words) covering:
- What it is and current version
- Key API patterns with brief code snippets
- Best practices (top 5-7)
- Common pitfalls to avoid (top 3-5)
- Breaking changes from recent versions (if any)
- Key types/methods/functions a developer needs to know

This summary will be loaded into an AI assistant's context, so make it practical and actionable. Focus on "what a developer needs to know to use this correctly" rather than history or theory.

### ===SUMMARY_END===

### ===FULL_RESEARCH_START===

Write comprehensive research (2500-4000 words) covering everything in the summary PLUS:
- Detailed API signatures and configuration options
- Advanced patterns and edge cases
- Performance considerations
- Integration with other technologies
- Troubleshooting common errors
- Links to key documentation pages
- Version history highlights

### ===FULL_RESEARCH_END===

Step 5 — Store results

After the research subagent returns:

1. Parse the two sections from the output (between the delimiter markers)
2. Create the directory: ~/Developer/github/gordonbeeming/learning-agent/topics/<slug>/
3. Write summary.md with the SUMMARY content
4. Write full-research.md with the FULL_RESEARCH content
5. Write metadata.json:

{
  "displayName": "<Human-readable name with version>",
  "slug": "<the-slug>",
  "researchedAt": "<current ISO timestamp>",
  "expiresAt": "<researchedAt + stalenessDays from config.json>",
  "versionInfo": "<version info discovered during research>",
  "subtopics": ["<list>", "<of>", "<key>", "<subtopics>", "<covered>"],
  "sources": ["<list of sources used, e.g. context7, learn.microsoft.com>"],
  "qualityScore": "<high if context7 returned good results, medium if web-only>"
}

6. Update ~/Developer/github/gordonbeeming/learning-agent/index.json:
   • Set lastUpdated to current ISO timestamp
   • Add/replace the entry in topics with:

{
  "displayName": "<same as metadata>",
  "researchedAt": "<same>",
  "expiresAt": "<same>",
  "versionInfo": "<same>",
  "subtopics": ["<same>"],
  "sources": ["<same>"],
  "summaryPath": "topics/<slug>/summary.md",
  "qualityScore": "<same>"
}

Step 6 — Git commit and push

cd ~/Developer/github/gordonbeeming/learning-agent
git add topics/<slug>/ index.json
git commit -m "research: <display name>"
git push

Step 7 — Return result

Output the summary content so the calling agent has the knowledge in context.