Research Note

research-note

End-to-end research skill: investigate a topic and produce a footnoted Markdown note.

Workflow

1. Understand the topic: Parse the user's research request
   • If a YouTube URL is included, queue transcript extraction for Step 2
   • If an X/Twitter URL (x.com/*/status/* or twitter.com/*/status/*) is included, queue FixTweet API fetch for Step 2
   • If a PDF file is provided, queue text extraction for Step 2
   • If a GitHub URL is included, queue API metadata + README fetch for Step 2
2. Parallel: Check existing content + Web research + Source acquisition (run concurrently)
   • 2a. Search the project for related existing notes. Read found notes to build context for comparison (insights emerge naturally from connecting new information to existing knowledge)
   • 2b. Use WebSearch to find sources. For URL content retrieval, use Task subagents (see "URL Content Fetching" below)
   • 2c. YouTube URL → extract transcript via yt-dlp → source-acquisition. For series/playlist research (finding cut or deferred topics), follow series-cut-topics
   • 2d. X/Twitter URL → fetch via FixTweet API → source-acquisition
   • 2e. PDF file → extract with Read tool → source-acquisition
   • 2f. GitHub URL → fetch metadata + README via API → source-acquisition
3. Evaluate source quality: Assess reliability of collected sources → source-quality-tiers
   • GitHub リポジトリの品質を stars 数で判断しない（バズった直後の数字は品質を保証しない）。コミット履歴・イシュー対応・実利用の形跡（実エンゲージメント）を併せて確認する
4. Share findings and gather feedback: Present key facts and discussion points to the user before generating the note
   • Explicitly ask: "Any areas you'd like me to dig deeper into?"
   • If the user raises questions, conduct additional research before proceeding
   • If the user says "no" or "go ahead", proceed to Step 5
   • Purpose: Prevent rework after note generation and incorporate the user's perspective
5. Confirm file placement: Consult the user on where to place the file. If a File Placement section is defined below under "Project Integration", follow its rules
6. Generate note: Write Markdown following the output rules below

   Splitting into multiple files: If the note covers multiple independent subtopics, consult the user about splitting. When splitting, cross-reference files with links. Run Steps 7-8 for each file

7. Generate Mermaid mindmap (conditional): Only when generation conditions are met (see "Mermaid Mindmap" below)
8. Parallel: Link insertion + Content verification (run concurrently)
   • 8a. Insert links to highly relevant existing files only
   • 8b. Verify each footnote URL actually supports the corresponding claim
9. Lint (if configured): Run the lint command from the project CLAUDE.md's 「品質ゲート」 section (or "Project Integration" below). If neither declares one, note 「散文 lint: 未設定」 instead of skipping silently
10. QA check: → qa-checklist

Output Rules

See writing-conventions for universal rules (citation format, footnote deduplication, citation integrity, headless Chrome fallback).

Source Quality

Prefer higher-tier sources. Do NOT cite a URL unless you have actually read the relevant content and confirmed it supports the claim. → source-quality-tiers

URL Content Fetching

→ fetch-web の戦略に従う（r.jina.ai 主、headless Chrome フォールバック）。

複数 URL は Agent subagent を並列で起動する。subagent はページ全文でなく必要な情報のサマリーのみを返すことでメインコンテキストを圧迫しない。

Source Acquisition

Acquisition commands and fallback procedures for each source type (YouTube / X / PDF / Wikipedia / note.com): → source-acquisition

Mermaid Mindmap

Not generated by default. Only generate when the following conditions are met, and place it just before the footnotes.

Generation Conditions

• Comparison notes: Comparing A vs B (adding evaluation axes is effective)
• Non-linear concept relationships: When heading structure alone cannot convey how concepts relate
• User explicitly requests it
• After file splitting: When files are split into single topics, comparison structure may be resolved, making the mindmap unnecessary

For standard notes, the H2 heading list provides sufficient structure overview — skip the mindmap.

Structure Rules (when generating)

• Root node matches the note title (wrapped in (( )))
• Level 1 maps to H2 headings (major categories)
• Level 2 contains key points per category (max 5)
• Level 3 only when necessary (avoid over-expansion)
• For comparison notes, include evaluation axes (superior/inferior/equivalent)

Template

## Mindmap

\`\`\`mermaid
mindmap
  root((Topic Name))
    Category A
      Point 1
      Point 2
    Category B
      Point 3
      Point 4
\`\`\`

WikiLinks (Optional)

If your project uses Obsidian or a similar wiki-link system, you can enable cross-referencing with [[filename]] syntax.

• Format: [[filename]] or [[filename|display text]]
• Omit file extensions
• Use the shortest unambiguous path
• Only link to directly relevant content — do not link just because files share a broad category
• Before inserting, use Glob to check for duplicate filenames. Use path-qualified form if ambiguous

If your project does not use WikiLinks, use standard Markdown links or omit cross-references entirely.

Quality Checklist

→ qa-checklist

Self-Improvement

• Feedback Capture: Extract generalizable principles from user feedback and execution issues
• Checklist Evolution: Add extracted principles to qa-checklist
• Triggers: Fetch failure patterns, new fallback procedures, source tier improvements

Project Integration

This skill works standalone, but can be customized for your project by adding sections below.

File Placement (customize per project)

Define directory mapping rules for generated notes. Example:

|Content Type|Directory|
|-|-|
|Technical content|docs/tech/|
|General knowledge|docs/topics/|

If no rules are defined, the skill will ask the user where to place each note.

Lint (customize per project)

If your project uses a Markdown linter, specify the command here. The skill will run it after generating a note. Example:

npx textlint <path>

If not defined, linting is skipped.

Cross-Skill Integration

This skill can hand off results to other skills in your project:

• Quality checking: After generating a note, invoke a quality/style-checking skill if available
• Presentation: When research results should become slides, hand off to a slide-creation skill
• Article drafting: When research should become a published article, hand off to a drafting skill

These integrations depend on which skills are installed in your project. No specific skill names are assumed.

Dependencies

• yt-dlp - YouTube transcript extraction
• curl + jq - API calls (X/Twitter, GitHub, Wikipedia, PubMed)
• puppeteer-core + turndown + Google Chrome - Headless Chrome fallback（fetch-web 経由）