start-vibing 4.4.2 → 4.4.4

package/template/.claude/skills/research/scripts/update-index.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# update-index.sh — regenerate /docs/research/index.md and per-folder
+# indexes from frontmatter of all docs. Idempotent.
+set -euo pipefail
+
+ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+DIR="${ROOT}/docs/research"
+INDEX="${DIR}/index.md"
+DEC_DIR="${DIR}/decisions"
+DEC_INDEX="${DEC_DIR}/index.md"
+MOC_DIR="${DIR}/moc"
+MOC_INDEX="${MOC_DIR}/index.md"
+
+mkdir -p "$DIR" "$DEC_DIR" "$MOC_DIR"
+
+fm_get() {
+  # fm_get <file> <key>
+  awk -v k="$2" '
+    /^---$/ { fm = !fm; next }
+    fm {
+      if (match($0, "^" k ":")) {
+        sub("^" k ":[[:space:]]*", ""); print; exit
+      }
+    }
+  ' "$1"
+}
+
+list_topics() {
+  find "$DIR" -maxdepth 1 -type f -name "*.md" ! -name "index.md" 2>/dev/null | sort
+}
+
+list_decisions() {
+  find "$DEC_DIR" -maxdepth 1 -type f -name "*.md" ! -name "index.md" 2>/dev/null | sort
+}
+
+list_mocs() {
+  find "$MOC_DIR" -maxdepth 1 -type f -name "*.md" ! -name "index.md" 2>/dev/null | sort
+}
+
+# ---- root index ----
+{
+  echo "# Research Index"
+  echo
+  echo "_Auto-generated by \`.claude/skills/research/scripts/update-index.sh\`. Do not edit by hand._"
+  echo
+  echo "## Topics"
+  echo
+  echo "| Topic | Date | Bucket | Status | Confidence | Sources |"
+  echo "|-------|------|--------|--------|------------|---------|"
+  for f in $(list_topics); do
+    SLUG=$(basename "$f" .md)
+    DATE=$(fm_get "$f" date); [ -z "$DATE" ] && DATE="—"
+    BUCKET=$(fm_get "$f" content_type_bucket); [ -z "$BUCKET" ] && BUCKET="—"
+    STATUS=$(fm_get "$f" freshness); [ -z "$STATUS" ] && STATUS="—"
+    CONF=$(fm_get "$f" confidence_summary); [ -z "$CONF" ] && CONF="—"
+    SRC=$(fm_get "$f" sources_count); [ -z "$SRC" ] && SRC="—"
+    echo "| [${SLUG}](./${SLUG}.md) | ${DATE} | ${BUCKET} | ${STATUS} | ${CONF} | ${SRC} |"
+  done
+  echo
+  echo "## Decisions (ADRs)"
+  echo
+  echo "| ADR | Date | Status |"
+  echo "|-----|------|--------|"
+  for f in $(list_decisions); do
+    SLUG=$(basename "$f" .md)
+    DATE=$(fm_get "$f" date); [ -z "$DATE" ] && DATE="—"
+    STAT=$(fm_get "$f" status); [ -z "$STAT" ] && STAT="—"
+    echo "| [${SLUG}](./decisions/${SLUG}.md) | ${DATE} | ${STAT} |"
+  done
+  echo
+  echo "## Maps of Content"
+  echo
+  for f in $(list_mocs); do
+    SLUG=$(basename "$f" .md)
+    echo "- [${SLUG}](./moc/${SLUG}.md)"
+  done
+} > "$INDEX"
+
+# ---- decisions index ----
+{
+  echo "# Architecture Decision Records"
+  echo
+  echo "_Auto-generated. Format: Nygard 2011._"
+  echo
+  for f in $(list_decisions); do
+    SLUG=$(basename "$f" .md)
+    DATE=$(fm_get "$f" date); [ -z "$DATE" ] && DATE="—"
+    STAT=$(fm_get "$f" status); [ -z "$STAT" ] && STAT="—"
+    TITLE=$(fm_get "$f" title); [ -z "$TITLE" ] && TITLE="$SLUG"
+    echo "- **[${SLUG}](./${SLUG}.md)** — ${TITLE} _(${DATE} · ${STAT})_"
+  done
+} > "$DEC_INDEX"
+
+# ---- moc index ----
+{
+  echo "# Maps of Content"
+  echo
+  for f in $(list_mocs); do
+    SLUG=$(basename "$f" .md)
+    echo "- [${SLUG}](./${SLUG}.md)"
+  done
+} > "$MOC_INDEX"
+
+echo "updated: $INDEX"
+echo "updated: $DEC_INDEX"
+echo "updated: $MOC_INDEX"

package/template/.claude/skills/research/scripts/verify-citations.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# verify-citations.sh — anti-hallucination gate.
+# Reads a rendered research doc + the session sources.jsonl/claims.jsonl,
+# verifies every citation: HTTP 200, quote greppable in cached snapshot,
+# DOI resolvable in Crossref. Emits JSON array to stdout. Exits non-zero
+# on any FAIL verdict.
+#
+# Usage:
+#   verify-citations.sh <doc.md> <session_dir>
+#
+# Dependencies: bash, jq, curl, grep. All present on dev/CI defaults.
+set -euo pipefail
+
+DOC="${1:?usage: verify-citations.sh <doc.md> <session_dir>}"
+SESSION_DIR="${2:?usage: verify-citations.sh <doc.md> <session_dir>}"
+
+[ -f "$DOC" ] || { echo "doc not found: $DOC" >&2; exit 2; }
+[ -d "$SESSION_DIR" ] || { echo "session dir not found: $SESSION_DIR" >&2; exit 2; }
+
+SOURCES="${SESSION_DIR}/sources.jsonl"
+CLAIMS="${SESSION_DIR}/claims.jsonl"
+[ -f "$SOURCES" ] || { echo "missing sources.jsonl" >&2; exit 2; }
+[ -f "$CLAIMS" ]  || { echo "missing claims.jsonl"  >&2; exit 2; }
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq is required" >&2; exit 2
+fi
+
+FAIL_COUNT=0
+RESULTS=()
+
+# Iterate every claim
+while IFS= read -r CLAIM_JSON; do
+  [ -z "$CLAIM_JSON" ] && continue
+  CID=$(echo "$CLAIM_JSON" | jq -r '.id')
+  SID=$(echo "$CLAIM_JSON" | jq -r '.source_id')
+  QUOTE=$(echo "$CLAIM_JSON" | jq -r '.quote')
+
+  SRC=$(grep -F "\"id\":\"$SID\"" "$SOURCES" || true)
+  if [ -z "$SRC" ]; then
+    RESULTS+=("$(jq -nc --arg cid "$CID" --arg sid "$SID" \
+      '{citation_id:$cid, source_id:$sid, url_status:"missing-source", quote_match:false, doi_status:null, verdict:"fail"}')")
+    FAIL_COUNT=$((FAIL_COUNT+1)); continue
+  fi
+
+  URL=$(echo "$SRC" | jq -r '.url // empty')
+  DOI=$(echo "$SRC" | jq -r '.doi // empty')
+  SNAP=$(echo "$SRC" | jq -r '.snapshot_path // empty')
+
+  # 1. URL reachability (HEAD, then GET if HEAD denied)
+  URL_STATUS="unknown"
+  if [ -n "$URL" ]; then
+    CODE=$(curl -fsSL -o /dev/null -w "%{http_code}" --max-time 12 -I "$URL" 2>/dev/null || echo "000")
+    if [ "$CODE" = "405" ] || [ "$CODE" = "403" ] || [ "$CODE" = "000" ]; then
+      CODE=$(curl -fsSL -o /dev/null -w "%{http_code}" --max-time 12 "$URL" 2>/dev/null || echo "000")
+    fi
+    URL_STATUS="$CODE"
+  fi
+
+  # 2. DOI Crossref check
+  DOI_STATUS="n/a"
+  if [ -n "$DOI" ]; then
+    DOI_CODE=$(curl -fsSL -o /dev/null -w "%{http_code}" --max-time 12 \
+      "https://api.crossref.org/works/${DOI}" 2>/dev/null || echo "000")
+    DOI_STATUS="$DOI_CODE"
+  fi
+
+  # 3. Quote-grep against snapshot
+  QUOTE_MATCH="false"
+  if [ -n "$SNAP" ] && [ -f "${CLAUDE_PROJECT_DIR:-.}/$SNAP" ]; then
+    if grep -qF -- "$QUOTE" "${CLAUDE_PROJECT_DIR:-.}/$SNAP"; then
+      QUOTE_MATCH="true"
+    else
+      # try whitespace-collapsed match
+      NEEDLE=$(echo "$QUOTE" | tr -s '[:space:]' ' ')
+      HAYSTACK=$(tr -s '[:space:]' ' ' < "${CLAUDE_PROJECT_DIR:-.}/$SNAP")
+      if echo "$HAYSTACK" | grep -qF -- "$NEEDLE"; then QUOTE_MATCH="true"; fi
+    fi
+  fi
+
+  # 4. Verdict
+  VERDICT="pass"
+  if [ "$QUOTE_MATCH" = "false" ]; then VERDICT="fail"; fi
+  if [ -n "$DOI" ] && [ "$DOI_STATUS" != "200" ]; then VERDICT="fail"; fi
+  if [ -z "$DOI" ] && [ "$URL_STATUS" != "200" ] && [ "$URL_STATUS" != "301" ] && [ "$URL_STATUS" != "302" ]; then
+    if [ "$VERDICT" = "pass" ] && [ "$QUOTE_MATCH" = "true" ]; then VERDICT="stale"; else VERDICT="fail"; fi
+  fi
+
+  [ "$VERDICT" = "fail" ] && FAIL_COUNT=$((FAIL_COUNT+1))
+
+  RESULTS+=("$(jq -nc \
+    --arg cid "$CID" --arg sid "$SID" \
+    --arg url "$URL_STATUS" --argjson qm "$QUOTE_MATCH" \
+    --arg doi "$DOI_STATUS" --arg verdict "$VERDICT" \
+    '{citation_id:$cid, source_id:$sid, url_status:$url, quote_match:$qm, doi_status:$doi, verdict:$verdict}')")
+done < "$CLAIMS"
+
+# Emit array
+printf '['
+FIRST=1
+for R in "${RESULTS[@]}"; do
+  if [ $FIRST -eq 1 ]; then FIRST=0; else printf ','; fi
+  printf '%s' "$R"
+done
+printf ']\n'
+
+[ "$FAIL_COUNT" -eq 0 ]

package/template/.claude/skills/research/templates/adr.md.tpl

@@ -0,0 +1,66 @@
+---
+title: "{{TITLE}}"
+adr_number: {{NNNN}}
+date: "{{DATE_YYYY_MM_DD}}"
+status: "{{STATUS}}"           # proposed | accepted | superseded-by-NNNN | deprecated | rejected
+deciders: [{{DECIDERS}}]
+related_research: "{{RESEARCH_DOC_PATH}}"
+session_id: "{{SESSION_ID}}"
+---
+
+# ADR-{{NNNN}}: {{TITLE}}
+
+_Format: Michael Nygard (2011), "Documenting Architecture Decisions"._
+
+## Status
+
+{{STATUS}}
+
+## Context
+
+{{CONTEXT}}
+
+## Decision
+
+{{DECISION}}
+
+## Consequences
+
+### Positive
+
+{{#each POSITIVE}}
+- {{TEXT}}
+{{/each}}
+
+### Negative
+
+{{#each NEGATIVE}}
+- {{TEXT}}
+{{/each}}
+
+### Neutral
+
+{{#each NEUTRAL}}
+- {{TEXT}}
+{{/each}}
+
+## Alternatives Considered
+
+{{#each ALTERNATIVE}}
+### {{NAME}}
+
+- **Why considered:** {{WHY}}
+- **Why rejected:** {{WHY_NOT}}
+{{/each}}
+
+## Reversibility
+
+- **Class:** {{REVERSIBILITY_CLASS}}   <!-- one-way-door | two-way-door (Bezos) -->
+- **Cost to reverse:** {{REVERSE_COST}}
+- **Trigger to reconsider:** {{REVERSE_TRIGGER}}
+
+## References
+
+- Research doc: [{{RESEARCH_DOC_PATH}}](../{{RESEARCH_DOC_PATH}})
+- Session evidence: `docs/research/.cache/sessions/{{SESSION_ID}}/`
+- Nygard 2011 — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

package/template/.claude/skills/research/templates/index.md.tpl

@@ -0,0 +1,25 @@
+# Research Index
+
+_Auto-generated by `.claude/skills/research/scripts/update-index.sh`. Do not edit by hand._
+
+## Topics
+
+| Topic | Date | Bucket | Status | Confidence | Sources |
+|-------|------|--------|--------|------------|---------|
+{{#each TOPIC}}
+| [{{SLUG}}](./{{SLUG}}.md) | {{DATE}} | {{BUCKET}} | {{FRESHNESS}} | {{CONFIDENCE}} | {{SOURCES_COUNT}} |
+{{/each}}
+
+## Decisions (ADRs)
+
+| ADR | Date | Status |
+|-----|------|--------|
+{{#each ADR}}
+| [{{NNNN}}-{{SLUG}}](./decisions/{{NNNN}}-{{SLUG}}.md) | {{DATE}} | {{STATUS}} |
+{{/each}}
+
+## Maps of Content
+
+{{#each MOC}}
+- [{{TITLE}}](./moc/{{SLUG}}.md)
+{{/each}}

package/template/.claude/skills/research/templates/moc.md.tpl

@@ -0,0 +1,39 @@
+---
+title: "{{THEME_TITLE}}"
+type: moc
+date: "{{DATE_YYYY_MM_DD}}"
+theme: "{{THEME_SLUG}}"
+---
+
+# MOC — {{THEME_TITLE}}
+
+_Map of Content (Nick Milo, "Linking Your Thinking"). A curated entry
+point that links related research docs around a theme._
+
+## Overview
+
+{{OVERVIEW}}
+
+## Topics in this map
+
+{{#each TOPIC}}
+- [{{TITLE}}](../{{SLUG}}.md) — {{ONE_LINER}}
+{{/each}}
+
+## ADRs in this map
+
+{{#each ADR}}
+- [ADR-{{NNNN}}: {{TITLE}}](../decisions/{{NNNN}}-{{SLUG}}.md)
+{{/each}}
+
+## Recurring concepts
+
+{{#each CONCEPT}}
+- **{{CONCEPT_NAME}}** — appears in: {{IN_DOCS}}
+{{/each}}
+
+## Open questions across topics
+
+{{#each OPEN_Q}}
+- {{TEXT}}
+{{/each}}

package/template/.claude/skills/research/templates/research-state.schema.json

@@ -0,0 +1,64 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://hakutaku.dev/schema/research-state-0.1.0.json",
+	"title": "research-state JSONL entry",
+	"description": "One JSON line per research run appended to docs/research/.research-state.jsonl",
+	"type": "object",
+	"required": ["topic_slug", "ts", "verdict"],
+	"additionalProperties": true,
+	"properties": {
+		"topic_slug": {
+			"type": "string",
+			"pattern": "^[a-z0-9][a-z0-9-]{1,59}$",
+			"description": "Kebab-case slug; matches /docs/research/<slug>.md filename."
+		},
+		"ts": {
+			"type": "string",
+			"format": "date-time",
+			"description": "UTC ISO-8601 timestamp of run completion."
+		},
+		"session_id": {
+			"type": "string",
+			"description": "Session directory name under docs/research/.cache/sessions/"
+		},
+		"verdict": {
+			"type": "string",
+			"enum": ["pass", "pass-with-warnings", "fail", "abort", "reuse"]
+		},
+		"content_type_bucket": {
+			"type": "string",
+			"enum": ["fast", "medium", "slow", "permanent", "unknown"]
+		},
+		"freshness_status": {
+			"type": "string",
+			"enum": ["fresh", "aging", "stale", "outdated", "missing"]
+		},
+		"playbook": {
+			"type": "string",
+			"enum": [
+				"ux-design",
+				"library-evaluation",
+				"api-integration",
+				"architectural-decision",
+				"market-competitive",
+				"academic-literature",
+				"news-current-events",
+				"security",
+				"pricing-cost",
+				"other"
+			]
+		},
+		"domain": { "type": "string" },
+		"lang": { "type": "string", "default": "en" },
+		"queries_used": { "type": "integer", "minimum": 0 },
+		"sources_cited": { "type": "integer", "minimum": 0 },
+		"findings_count": { "type": "integer", "minimum": 0 },
+		"disagreements_count": { "type": "integer", "minimum": 0 },
+		"verify_pass": { "type": "integer", "minimum": 0 },
+		"verify_stale": { "type": "integer", "minimum": 0 },
+		"verify_fail": { "type": "integer", "minimum": 0 },
+		"duration_seconds": { "type": "number" },
+		"doc_path": { "type": "string" },
+		"adr_path": { "type": ["string", "null"] }
+	}
+}

package/template/.claude/skills/research/templates/research.md.tpl

@@ -0,0 +1,117 @@
+---
+title: "{{TITLE}}"
+slug: "{{SLUG}}"
+date: "{{DATE_YYYY_MM_DD}}"
+lang: "{{LANG}}"
+content_type_bucket: "{{BUCKET}}"            # fast | medium | slow | permanent
+freshness: "{{FRESHNESS}}"                    # fresh | aging | stale | outdated
+freshness_window_days: {{WINDOW_DAYS}}
+playbook: "{{PLAYBOOK}}"
+domain: "{{DOMAIN}}"
+sources_count: {{SOURCES_COUNT}}
+findings_count: {{FINDINGS_COUNT}}
+disagreements_count: {{DISAGREEMENTS_COUNT}}
+open_questions_count: {{OPEN_Q_COUNT}}
+confidence_summary: "{{CONFIDENCE_SUMMARY}}"  # e.g. "5 high · 3 medium · 1 low"
+concepts:
+{{CONCEPTS_YAML_LIST}}
+session_id: "{{SESSION_ID}}"
+---
+
+# Research: {{TITLE}}
+
+> Bucket: **{{BUCKET}}** · Status: **{{FRESHNESS}}** · Confidence: {{CONFIDENCE_SUMMARY}}
+> Session: `docs/research/.cache/sessions/{{SESSION_ID}}/`
+
+## Executive summary
+
+{{EXEC_SUMMARY}}
+
+## Question
+
+{{ORIGINAL_QUESTION}}
+
+## Ontology Map
+
+Concepts and their relationships using the SKOS-adapted vocabulary
+(see `.claude/skills/research/references/ontology-patterns.md`).
+
+```
+{{ONTOLOGY_RELATIONS}}
+```
+
+## Findings
+
+{{#each FINDING}}
+### Finding {{ID}} — {{TITLE}}
+
+{{ASSERTION}}
+
+**Confidence:** {{CONFIDENCE}}{{#if FRESHNESS_WARNING}} · _Freshness warning: {{FRESHNESS_WARNING}}_{{/if}}{{#if TRIANGULATION_WARNING}} · _Triangulation: {{TRIANGULATION_WARNING}}_{{/if}}
+
+Evidence:
+
+{{#each EVIDENCE}}
+> "{{QUOTE}}" [{{SOURCE_ID}}]
+> URL: {{URL}}
+> Accessed: {{ACCESSED_AT}}
+> Verify: {{VERIFY_METHOD}}
+{{/each}}
+
+{{/each}}
+
+## Disagreements
+
+{{#each DISAGREEMENT}}
+### {{TOPIC}}
+
+- **Position A** ([{{SRC_A}}]): {{POSITION_A}}
+- **Position B** ([{{SRC_B}}]): {{POSITION_B}}
+- **Resolution requires:** {{RESOLUTION_HINT}}
+{{/each}}
+
+## Recommendations
+
+### DO
+
+{{#each RECOMMENDATION_DO}}
+- {{TEXT}} — _{{REASON}}_
+{{/each}}
+
+### AVOID
+
+{{#each RECOMMENDATION_AVOID}}
+- {{TEXT}} — _{{REASON}}_
+{{/each}}
+
+## Implementation Path
+
+{{#each STEP}}
+{{N}}. {{TEXT}}
+{{/each}}
+
+## Open Questions
+
+{{#each OPEN_Q}}
+- {{TEXT}}
+{{/each}}
+
+## Dead Ends
+
+_Searched but not found / not applicable_
+
+{{#each DEAD_END}}
+- {{TEXT}}
+{{/each}}
+
+## Sources
+
+| ID | Title | Publisher | Authority (1-5) | Independence | Accessed | URL |
+|----|-------|-----------|-----------------|--------------|----------|-----|
+{{#each SOURCE}}
+| {{ID}} | {{TITLE}} | {{PUBLISHER}} | {{AUTHORITY_LEVEL}} | {{INDEPENDENCE}} | {{ACCESSED_AT}} | {{URL}} |
+{{/each}}
+
+---
+
+_Generated by the `research` skill. Pipeline: scout → query → synthesize → verify. Verify status: {{VERIFY_STATUS}}._

package/template/.claude/agents/research-web.md

@@ -1,164 +0,0 @@
----
-name: research-web
-description: "AUTOMATICALLY invoke BEFORE implementing any new feature or technology. Triggers: new feature, new technology, 'search', 'find info'. Web research specialist. PROACTIVELY searches for current solutions."
-model: sonnet
-color: cyan
-tools: WebSearch, WebFetch, Read, Write, Glob, Grep
----
-
-# Research Web Agent
-
-Targeted web research for development decisions. Output goes to `/docs/research/`.
-
-## Research Flow
-
-```
-1. Understand Question → Define problem + constraints
-2. Check /docs/research/ → Reuse if fresh (<3 months)
-3. Ontology Map → Identify concepts, relationships, constraints
-4. Query (3-5 searches) → [topic] [aspect] [2025-2026] [context]
-5. Triangulate → Same claim in 3+ independent sources
-6. Structure → Ontology-based output (concepts → relationships → decisions)
-7. Save → Write to /docs/research/[topic].md
-```
-
-## Query Strategy
-
-```
-[technology] + [specific aspect] + [2025 OR 2026] + [project context]
-
-Examples:
-- "Playwright authentication 2026 best practices Next.js"
-- "MongoDB aggregation pipeline patterns 2025-2026"
-- "React Server Components data fetching 2026"
-```
-
-### Source Priority
-
-1. Official documentation
-2. GitHub issues/discussions
-3. Stack Overflow (recent answers, 2025-2026)
-4. Technical blogs (verified authors)
-5. Conference talks/presentations
-
-## UI/UX Research Flow (for UI tasks)
-
-When research involves UI/UX features, follow this structured flow:
-
-```
-1. Competitor Analysis
-   - Identify 3-5 competitors solving same user problem
-   - Run heuristic evaluation (Nielsen's 10 heuristics)
-   - Score issues 0-4 by severity
-
-2. Design System Check
-   - Check existing patterns (shadcn/ui, Radix, etc.)
-   - Map component to known pattern (Button, Dialog, Combobox)
-   - Cross-reference WCAG 2.1 for the component category
-
-3. User Flow Mapping
-   - Define entry/exit points for the journey
-   - Map happy path + 2 error/edge-case paths
-   - Identify decision points needing UI affordances
-
-4. Accessibility Audit
-   - Automated scan first (axe, Lighthouse)
-   - Manual keyboard navigation check
-   - Screen reader test plan (NVDA + VoiceOver)
-   - Color contrast AA minimum, AAA for body text
-```
-
-## Ontology-Based Structuring
-
-Structure findings using relationships, not flat lists:
-
-```
-Concept → relationships → constraints → recommended-pattern → implementation-path
-
-Example:
-  Button is-a InteractiveElement
-  Button has-a Label, Icon, LoadingState
-  Button depends-on AccessibilityRole (role="button")
-  Button constrained-by TouchTarget (min 44x44px mobile)
-  Button resolved-by shadcn/ui Button + CVA variants
-```
-
-### Relationship Types
-
-| Relationship | Meaning | Example |
-|-------------|---------|---------|
-| `is-a` | Inheritance/subtype | Dialog is-a Overlay |
-| `has-a` | Composition | Form has-a ValidationSchema |
-| `depends-on` | Dependency | AuthFlow depends-on SessionStore |
-| `constrained-by` | Limitation | MobileNav constrained-by ViewportWidth |
-| `resolved-by` | Implementation | DataFetch resolved-by TanStackQuery |
-| `precedes` | Ordering | Research precedes Implementation |
-
-## Output Format
-
-Save to `/docs/research/[topic-kebab-case].md`:
-
-```markdown
-# Research: [Topic]
-
-**Date:** YYYY-MM-DD
-**Freshness:** fresh | aging | stale
-**Stack:** [relevant tech]
-
-## Problem
-
-[1-2 sentences: what we're solving]
-
-## Ontology Map
-
-[Key concepts and their relationships using is-a, has-a, depends-on, constrained-by, resolved-by]
-
-## Findings
-
-### [Finding 1 Title]
-**Source:** [URL] ([date])
-**Relevance:** high | medium
-
-[Concise summary + code example if applicable]
-
-### [Finding 2 Title]
-...
-
-## Recommendations
-
-### DO
-1. [Best practice] — why
-
-### AVOID
-1. [Anti-pattern] — why
-
-## Implementation Path
-
-1. [Step 1]
-2. [Step 2]
-
-## Sources
-
-| Title | URL | Date |
-|-------|-----|------|
-| ... | ... | ... |
-```
-
-## Freshness Rules
-
-| Age | Status | Action |
-|-----|--------|--------|
-| < 3 months | Fresh | Use directly |
-| 3-6 months | Aging | Verify still valid |
-| 6-12 months | Stale | Update recommended |
-| > 12 months | Outdated | Full re-research |
-
-## Critical Rules
-
-1. **CHECK /docs/research/ FIRST** — avoid duplicate research
-2. **CITE SOURCES** — every finding needs a URL
-3. **2025-2026 CONTENT** — prefer recent, flag anything older than 12 months
-4. **TRIANGULATE** — same claim in 3+ sources before treating as truth
-5. **ONTOLOGY STRUCTURE** — map concepts and relationships, not just flat summaries
-6. **ACTIONABLE OUTPUT** — every finding must have an implementation path
-7. **CONCISE** — bullet points over paragraphs, tables over prose