aiskillstore/research-storage

Research Storage Skill

This skill defines conventions for storing and retrieving research data collected by dokhak agents. Research files are cached to enable reuse and reduce redundant web searches.

Quick Reference for Agents

| Agent | Uses This Skill For | |-------|---------------------| | researcher | Directory resolution, research.md writing, multi-tier lookup | | research-collector | summary.md, sources.md writing to .research/init/ | | writer | Reading research files (read-only) | | structure-designer | Reading init research (read-only) |

Standard Loading Pattern

All agents should reference this skill for:

• Normalization functions: normalizeChapter, normalizeSection, generateSlug
• Multi-tier directory resolution: Handling legacy naming inconsistencies
• File format templates: research.md, sources.md, summary.md

Read("skills/research-storage/SKILL.md")

Directory Structure

project-root/
├── .research/                          # Research cache directory
│   ├── init/                           # /init command research
│   │   ├── summary.md                  # Structured research summary
│   │   └── sources.md                  # Source registry with reliability
│   │
│   └── sections/                       # /write command section research
│       ├── 01-1-introduction/
│       │   ├── research.md             # Section research results
│       │   └── sources.md              # Section sources
│       ├── 01-2-core-concepts/
│       │   ├── research.md
│       │   └── sources.md
│       └── {chapter}-{section}-{slug}/
│           ├── research.md
│           └── sources.md

Naming Convention

Section Directory Pattern (CANONICAL)

Format: {chapter}-{section}-{slug}

| Component | Format | Canonical Example | Non-canonical (avoid) | | --------- | ----------------------- | ----------------- | --------------------- | | chapter | Zero-padded 2 digits | 01, 02, 10 | 1, 2 | | section | Single digit (NO padding) | 1, 2, 3 | 01, 02 | | slug | Kebab-case lowercase | core-concepts | Core-Concepts |

Canonical Examples:

• Chapter 1, Section 2, "Core Concepts" → 01-2-core-concepts ✓
• Chapter 3, Section 1, "Getting Started" → 03-1-getting-started ✓
• Chapter 10, Section 3, "Advanced Patterns" → 10-3-advanced-patterns ✓

Non-canonical (may exist from legacy/inconsistency):

• 1-2-core-concepts (chapter not padded)
• 01-02-core-concepts (section padded)
• 01-2-Core-Concepts (slug not lowercase)

Normalization Functions

CRITICAL: All agents MUST use these normalization functions to ensure consistency.

normalizeChapter(chapter)

Converts any chapter format to canonical 2-digit zero-padded string.

Input: "1" or "01" or 1 or "001"
Output: "01" (always 2-digit zero-padded string)

Process:
1. Convert to integer: parseInt(chapter, 10)
2. Zero-pad to 2 digits: String(n).padStart(2, '0')

Examples:
- "1" → "01"
- "01" → "01"
- "10" → "10"
- 1 → "01"
- "001" → "01"

normalizeSection(section)

Converts any section format to canonical single-digit string (no padding).

Input: "1" or "01" or 1
Output: "1" (single digit, no padding)

Process:
1. Convert to integer: parseInt(section, 10)
2. Convert to string: String(n)

Examples:
- "1" → "1"
- "01" → "1"
- "3" → "3"
- "03" → "3"

generateSlug(title)

Converts title to canonical kebab-case slug.

Input: Any title string
Output: Lowercase kebab-case slug

Process:
1. Convert to lowercase: title.toLowerCase()
2. Replace spaces with hyphens: replace(/\s+/g, '-')
3. Remove special characters (keep a-z, 0-9, -): replace(/[^a-z0-9-]/g, '')
4. Collapse multiple hyphens: replace(/-+/g, '-')
5. Trim leading/trailing hyphens: replace(/^-|-$/g, '')

Examples:
- "Core Concepts" → "core-concepts"
- "What is React?" → "what-is-react"
- "Setup & Installation" → "setup-installation"
- "  Multiple   Spaces  " → "multiple-spaces"
- "C++ Programming" → "c-programming"

buildCanonicalPath(chapter, section, title)

Builds the canonical directory path.

Input: chapter, section, title
Output: ".research/sections/{canonical_chapter}-{canonical_section}-{canonical_slug}/"

Process:
1. canonical_chapter = normalizeChapter(chapter)
2. canonical_section = normalizeSection(section)
3. canonical_slug = generateSlug(title)
4. return ".research/sections/{canonical_chapter}-{canonical_section}-{canonical_slug}/"

Example:
- buildCanonicalPath("1", "02", "Core Concepts")
- → ".research/sections/01-2-core-concepts/"

File Path Generation

For /init Research

.research/init/summary.md
.research/init/sources.md

For Section Research

.research/sections/{chapter}-{section}-{slug}/research.md
.research/sections/{chapter}-{section}-{slug}/sources.md

Example: Section 1.2 "Core Concepts"

.research/sections/01-2-core-concepts/research.md
.research/sections/01-2-core-concepts/sources.md

File Format Templates

summary.md (for /init)

# Research Summary

> Generated: {YYYY-MM-DD}
> Topic: {topic}
> Domain: {domain}

## Key Concepts

### {Concept 1}

- **Definition**: {clear definition}
- **Importance**: {why it matters}
- **Source**: [{source name}]({url})

### {Concept 2}

- **Definition**: {clear definition}
- **Importance**: {why it matters}
- **Source**: [{source name}]({url})

## Learning Path

1. **Prerequisites**: {comma-separated list}
2. **Fundamentals**: {comma-separated list}
3. **Core Skills**: {comma-separated list}
4. **Advanced Topics**: {comma-separated list}

## Current Trends ({current_year})

- {trend 1 with source link}
- {trend 2 with source link}

## Domain-Specific Information

{domain-specific sections based on domain-profiles skill}

sources.md (for both /init and sections)

# Source Registry

> Section: {section_id or "init"}
> Generated: {YYYY-MM-DD}

## Primary Sources (High Reliability)

| Source | URL   | Type          | Last Verified |
| ------ | ----- | ------------- | ------------- |
| {name} | {url} | Official Docs | {YYYY-MM-DD}  |
| {name} | {url} | Official Docs | {YYYY-MM-DD}  |

## Secondary Sources (Medium Reliability)

| Source | URL   | Type     | Notes   |
| ------ | ----- | -------- | ------- |
| {name} | {url} | Tutorial | {notes} |
| {name} | {url} | Blog     | {notes} |

## Rejected Sources

| Source | Reason            |
| ------ | ----------------- |
| {name} | Outdated (year)   |
| {name} | Unreliable author |

research.md (for sections)

# Research: {Section Title}

> Section: {chapter}.{section} {title}
> Target Pages: {N}p
> Generated: {YYYY-MM-DD}

## Scope

{Brief description of what this section covers}

## Key Concepts

### {Concept 1}

- **Definition**: {definition}
- **Source**: [{name}]({url})

### {Concept 2}

- **Definition**: {definition}
- **Source**: [{name}]({url})

## Code Examples

### {Example Title}

```{language}
{code}
```

> Source: [{name}]({url})

## Common Pitfalls

1. **{Pitfall 1}**: {description}
   - **Cause**: {why it happens}
   - **Solution**: {how to avoid}

2. **{Pitfall 2}**: {description}
   - **Cause**: {why it happens}
   - **Solution**: {how to avoid}

## Practical Insights

- {insight 1 with source link}
- {insight 2 with source link}

## Subtopic Coverage

| Subtopic | Status   | Source            |
| -------- | -------- | ----------------- |
| {name}   | Complete | [{source}]({url}) |
| {name}   | Partial  | [{source}]({url}) |
| {name}   | Missing  | -                 |

Directory Resolution Strategy

When locating research directories, use multi-tier search to handle naming inconsistencies from legacy data or different generation sources.

Why Multi-Tier Search?

Research directories may have been created with inconsistent naming:

| Inconsistency Type | Example Mismatch | | ---------------------- | ------------------------------------------ | | Chapter padding | 1-2-intro vs 01-2-intro | | Section padding | 01-02-intro vs 01-2-intro | | Slug case | 01-2-Core-Concepts vs 01-2-core-concepts | | Slug special chars | 01-2-whats-new? vs 01-2-whats-new | | Combined inconsistency | 1-02-What's New? vs 01-2-whats-new |

Multi-Tier Search Algorithm

⚠️ CRITICAL: Glob Returns Files Only

Glob does NOT return directories. All patterns MUST end with a filename (e.g., /research.md).

| Pattern | Result | |---------|--------| | .research/sections/*9-1* | ❌ Empty (matches directory, not returned) | | .research/sections/*9-1*/research.md | ✅ Returns file path | | .research/sections/*9-1*/* | ✅ Returns all files in matching dirs |

Execute tiers in order. Stop at first successful match.

Tier 1: Canonical Exact Match (Primary)

Search using fully normalized canonical path.

canonical_chapter = normalizeChapter(chapter)  # "1" → "01"
canonical_section = normalizeSection(section)  # "02" → "2"
canonical_slug = generateSlug(title)           # "Core Concepts" → "core-concepts"

Glob(".research/sections/{canonical_chapter}-{canonical_section}-{canonical_slug}/research.md")

Example: Glob(".research/sections/01-2-core-concepts/research.md")

Tier 2: Canonical Chapter-Section, Any Slug

If Tier 1 fails, search with canonical chapter-section but wildcard slug.

Glob(".research/sections/{canonical_chapter}-{canonical_section}-*/research.md")

Example: Glob(".research/sections/01-2-*/research.md")

This catches slug variations like Core-Concepts, core_concepts, etc.

Tier 3: Non-Padded Chapter Variation

If Tier 2 fails, try without chapter zero-padding (legacy compatibility).

raw_chapter = String(parseInt(chapter, 10))  # "01" → "1"

Glob(".research/sections/{raw_chapter}-{canonical_section}-*/research.md")

Example: Glob(".research/sections/1-2-*/research.md")

Tier 4: Flexible Pattern Match (Last Resort)

If all above fail, use section number and first slug keyword.

first_keyword = generateSlug(title).split('-')[0]  # "core-concepts" → "core"

Glob(".research/sections/*-{canonical_section}-*{first_keyword}*/research.md")

Example: Glob(".research/sections/*-2-*core*/research.md")

Resolution Output Format

Return resolution result in XML format:

<directory_resolution>
  <input>
    <chapter>{original_chapter}</chapter>
    <section>{original_section}</section>
    <title>{original_title}</title>
  </input>
  <canonical>
    <chapter>{normalized_chapter}</chapter>
    <section>{normalized_section}</section>
    <slug>{normalized_slug}</slug>
    <path>{canonical_path}</path>
  </canonical>
  <resolution>
    <resolved_path>{matched_path OR canonical_path}</resolved_path>
    <existing>{true|false}</existing>
    <match_tier>{1|2|3|4|new}</match_tier>
  </resolution>
</directory_resolution>

Resolution Logic Summary

function resolveResearchDirectory(chapter, section, title):
  # Normalize inputs
  c = normalizeChapter(chapter)
  s = normalizeSection(section)
  slug = generateSlug(title)
  canonical = ".research/sections/{c}-{s}-{slug}/"

  # Tier 1: Exact canonical
  result = Glob("{canonical}research.md")
  if result: return { path: canonical, existing: true, tier: 1 }

  # Tier 2: Canonical chapter-section, any slug
  result = Glob(".research/sections/{c}-{s}-*/research.md")
  if result: return { path: parent(result[0]), existing: true, tier: 2 }

  # Tier 3: Non-padded chapter
  raw_c = String(parseInt(chapter, 10))
  result = Glob(".research/sections/{raw_c}-{s}-*/research.md")
  if result: return { path: parent(result[0]), existing: true, tier: 3 }

  # Tier 4: Flexible pattern
  keyword = slug.split('-')[0]
  result = Glob(".research/sections/*-{s}-*{keyword}*/research.md")
  if result: return { path: parent(result[0]), existing: true, tier: 4 }

  # No match - use canonical for new directory
  return { path: canonical, existing: false, tier: "new" }

Usage Patterns

Checking Existing Research (UPDATED)

IMPORTANT: Do NOT use simple Glob. Use the multi-tier resolution strategy above.

# OLD (may miss existing research due to naming inconsistency)
Glob(".research/sections/{chapter}-{section}-{slug}/research.md")

# NEW (handles all variations)
resolution = resolveResearchDirectory(chapter, section, title)
existing_research = resolution.existing
research_dir = resolution.resolved_path

Returns resolved directory path and existence status.

Reading Research Files

When consuming research, read files directly in agent context:

Read(".research/init/summary.md")
Read(".research/sections/01-2-core-concepts/research.md")

Saving Research Results

Agents should Write files following the templates above:

Write(".research/init/summary.md", content)
Write(".research/sections/01-2-core-concepts/research.md", content)

Agent-Specific Guidelines

research-collector Agent

• Outputs to: .research/init/summary.md, .research/init/sources.md
• Creates directory if not exists
• Returns confirmation only: research_saved:.research/init/

researcher Agent

• Outputs to: .research/sections/{id}/research.md, .research/sections/{id}/sources.md
• Checks existing research via Subtopic Coverage table
• Appends to existing if partial coverage
• Returns confirmation only: research_saved:{output_dir}

Consumer Agents (structure-designer, writer)

• Receive file paths in prompt
• Read files directly in their own context
• Do not modify research files

XML Output Schemas

Standardized XML schemas for agent communication. All agents should use these formats for consistency.

Research Result Schema

Used by research-collector and researcher agents:

<research_result domain="{technology|history|science|arts|general}" status="OK|PARTIAL|ERROR">
  <summary>
    <sources_count>{N}</sources_count>
    <concepts_count>{N}</concepts_count>
    <output_path>{path}</output_path>
    <generated>{YYYY-MM-DD}</generated>
  </summary>

  <authoritative_sources>
    - [Source Name](url) - {reliability: high|medium}
  </authoritative_sources>

  <key_concepts>
    - **{Term}**: {Definition}
  </key_concepts>

  <learning_path>
    1. Prerequisites: {list}
    2. Fundamentals: {list}
    3. Core Skills: {list}
    4. Advanced: {list}
  </learning_path>

  <!-- Domain-specific sections as per domain-profiles -->
</research_result>

Directory Resolution Schema

Used by researcher agent for path resolution:

<directory_resolution>
  <input>
    <chapter>{original_chapter}</chapter>
    <section>{original_section}</section>
    <title>{original_title}</title>
  </input>
  <canonical>
    <chapter>{normalized_chapter}</chapter>
    <section>{normalized_section}</section>
    <slug>{normalized_slug}</slug>
    <path>{canonical_path}</path>
  </canonical>
  <resolution status="FOUND|NEW">
    <resolved_path>{matched_path OR canonical_path}</resolved_path>
    <existing>{true|false}</existing>
    <match_tier>{1|2|3|4|new}</match_tier>
  </resolution>
</directory_resolution>

Subtopic Coverage Schema

Used within research files to track coverage:

<subtopic_coverage>
  <subtopic name="{name}" status="Complete|Partial|Missing">
    <source>{url or "pending"}</source>
  </subtopic>
</subtopic_coverage>

Status Values Reference

| Status | Context | Meaning | |--------|---------|---------| | OK | research_result | All subtopics covered, sufficient sources | | PARTIAL | research_result | Some subtopics missing or incomplete | | ERROR | research_result | Critical failure (e.g., no sources found) | | FOUND | directory_resolution | Existing research directory located | | NEW | directory_resolution | No existing research, use canonical path |

---

Error Handling

| Scenario | Action | | ------------------------------ | ----------------------------------- | | .research/ directory missing | Auto-create on first write | | Research file not found | Conduct fresh research | | Read failure | Log warning, conduct fresh research | | Write failure | Report error, do not update task.md |

.gitignore Recommendation

Research files are regenerable and should typically be ignored:

# Research cache (regenerable)
.research/