Research Frontmatter

Enforce standard YAML frontmatter on research documents so GitHub renders metadata as a table and readers can judge staleness.

Quick Start

# Validate all research documents
uv run ${CLAUDE_SKILL_DIR}/scripts/validate_research_docs.py --format text

# Check staleness only
uv run ${CLAUDE_SKILL_DIR}/scripts/validate_research_docs.py --staleness-only

# Resolve research path (JD-aware)
uv run ${CLAUDE_SKILL_DIR}/scripts/resolve_research_path.py --format json

# Override research directory
uv run ${CLAUDE_SKILL_DIR}/scripts/validate_research_docs.py --research-dir docs/30-research

Required Frontmatter

Every research file MUST have these 5 fields:

---
title: "Human-readable title"
version: "1.0.0"
status: Published           # Published | Draft | Living Document
created: YYYY-MM-DD
last_updated: YYYY-MM-DD
---

Optional fields (slug, tags, aliases, promoted_at, last_refreshed, sources) MAY follow.

JD-Aware Path Resolution

The skill auto-detects Johnny.Decimal structure:

1. Look for .jd-config.json at project root
2. Find area containing "research" (default: prefix 30)
3. Construct path: {root}/{prefix}-{name}/ (e.g. docs/30-research/)
4. Fall back to docs/research/ if no JD config

This applies to both validation and the deep-research promote workflow.

Validation Rules

Version Increment

• Patch (1.0.0 -> 1.0.1): Typo fixes, formatting, minor clarifications
• Minor (1.0.0 -> 1.1.0): New sections, updated examples
• Major (1.0.0 -> 2.0.0): Complete rewrite, fundamental scope change

README Index Format

The research README.md MUST use these columns:

| Topic | Version | Status | Created | Last Updated |

Integration

• deep-research: Promote uses JD-aware path resolution for Tier 2 output
• doc-freshness: Research docs with last_updated qualify for deep scanning
• jd-docs: Area 30-research is the default research home in JD structure

Template

New research files should follow the TEMPLATE.md in the research directory.

See WORKFLOW.md for detailed procedures. See EXAMPLES.md for usage examples. See TROUBLESHOOTING.md for common issues.