dhm

dhm — data-hive-mind operations

Single skill that owns reading + maintaining the team wiki at Artemis-xyz/data-hive-mind.

The wiki is durable team knowledge — architecture, conventions, decisions (ADRs), postmortems, playbooks, entity pages. It sits above Notion (session-scope) and Linear (ticket-scope). See wiki/decisions/2026-04-22-four-tier-knowledge-model.md in the wiki for the full tier design.

Five modes. Pick by intent:

========================================

Query mode — answer a question from the wiki

Status: implemented (Slice 1b, TheClauu v0.3.26+)

Answer a question using durable team knowledge already captured in the wiki. This is the default mode if the user says /theclauu:dhm <question> with no leading mode keyword.

Step 1 — check the pre-injected cache first

The SessionStart hook injects wiki content into the agent's context as part of <theclauu-hive-mind-context>. Before fetching anything, look in that JSON for wiki.relevant_pages[*].content. Pages always present:

• INDEX.md (table of contents)
• CLAUDE.md (schema + maintenance rules)
• wiki/entities/<current-repo>.md (if it exists)
• Pages matching the current repo name and recently edited pages (up to the byte budget)

If the cache is missing or stale, fall through to step 2.

Step 2 — fetch what the cache didn't already have

For pages not in the cache, use gh api:

gh api /repos/Artemis-xyz/data-hive-mind/contents/wiki/<path>.md \
  --jq '.content' | base64 -d

Or if the user has a local clone at a known path (e.g. ~/DuneAnalytics/dex_trades/data-hive-mind/), read from there directly — no network round-trip.

Step 3 — answer the question

• Cite page paths. Every claim sourced from the wiki ends with a file reference the engineer can open, e.g. wiki/conventions/dbt-scd2.md.
• Say "not in the wiki" when it isn't. Don't hallucinate. If the wiki doesn't cover the question, say so, and suggest: "file this as a new wiki page via /theclauu:dhm ingest once Slice 4 lands, or write the ADR by hand in the meantime."
• Prefer quoting to paraphrasing for rules and conventions — the exact phrasing often matters (e.g. what counts as a recognized schema name).

Output formats

Default: inline markdown answer with citations.

If the user asks for a different format:

• Markdown file: write under /tmp/dhm-query-<timestamp>.md and tell the user the path so they can open it in their editor.
• Summary slide deck (Marp): write a .md with Marp frontmatter to /tmp/dhm-query-<timestamp>.md.
• Diagram: render via matplotlib or mermaid-code-block in the answer.

When to write the answer back into the wiki

If the user's question surfaces a durable insight that belongs in the wiki (a pattern, decision, playbook), suggest filing it — but don't do it without confirmation. The wiki is a curated surface, not a dumping ground.

========================================

Ingest mode — drop a source into raw/

Status: not implemented yet (Slice 4). Do not attempt via this skill. For now, instruct the user to:

1. Manually drop the source file under data-hive-mind/raw/<type>/YYYY-MM-DD-<slug>.<ext>.
2. Commit + push directly to main (per the feedback_data_hive_mind_direct_to_main.md feedback — is solo-owned the repo for now).

raw/ subfolders:

• postmortems/ — incident transcripts, Slack on-call exports
• linear-exports/ — closed epic transcripts worth preserving
• notion-promoted/ — Notion pages queued for wiki compile
• pr-discussions/ — landmark PR comment exports
• articles/ — external reading (papers, blog posts)

========================================

Compile mode — raw/ → wiki/

Status: not implemented yet (Slice 4).

Planned behavior: read raw/ files that haven't been compiled yet, extract patterns / entities / decisions, write or update wiki/ pages, maintain backlinks + INDEX.md.

========================================

Promote mode — PR / Notion → wiki/

Status: implemented (Slice 4, TheClauu v0.4.2+)

Scan a source — default: the current branch's open PR; fallback: an explicit PR URL, branch name, or a Notion page URL — for wiki-worthy sections and promote them to pages in Artemis-xyz/data-hive-mind.

Helper module: plugins/theclauu/bin/promote_to_wiki.py

Step 1 — resolve the source

Default source: current branch's open PR

# Detect current branch
git branch --show-current

# Find open PR for the branch
gh pr view --json number,title,body,url,labels

If gh pr view fails (no PR open, or detached HEAD), fall through to the explicit-arg path.

Explicit args (in priority order):

1. --pr <URL-or-number> — fetch via fetch_pr_content(repo, pr_number) in promote_to_wiki.py.
2. --branch <name> — run gh pr list --head <name> --json number then fetch that PR.
3. --notion <URL> — extract the Notion page ID from the URL (last hex segment), fetch full page text via bin/sources/notion.py, use that as the source text.
4. Bare text piped via stdin — read sys.stdin directly.

Compose the source text as: PR title + PR body + (if any linked issue bodies are reachable, append them).

Step 2 — ask for the wiki repo path

The wiki repo is a local clone of Artemis-xyz/data-hive-mind. Ask once and cache the answer in ~/.theclauu/config.json under "wiki_repo_path".

AskUserQuestion: "Where is your local clone of data-hive-mind?
(Default: ../data-hive-mind/ relative to this repo — press Enter to accept)"

Fall back to ../data-hive-mind/ if the user presses Enter or the key is already cached. Expand ~ and relative paths before passing to the helper.

Skip asking if --wiki-path <path> was passed as an argument.

Step 3 — scan the source text

Call scan_text(source_text) from bin/promote_to_wiki.py. This returns a list[WikiCandidate] where each candidate carries:

Field	Description
category	decisions / playbooks / conventions / incidents / entities / concepts
suggested_path	e.g. wiki/decisions/2026-04-22-iceberg.md
title	inferred from the first heading in the matched section
body_excerpt	first ~500 chars of the matched section

Wiki-worthiness heuristics (in precedence order):

1. ADR — two or more of: Decision:, Rationale:, Status: markers → wiki/decisions/YYYY-MM-DD-<slug>.md
2. Postmortem — two or more of: Incident:, Timeline:, Root cause: → wiki/incidents/YYYY-MM-DD-<slug>.md
3. Playbook — three or more numbered steps (1., Step 1:, Step 1.) → wiki/playbooks/<slug>.md
4. Convention — imperative rule (Always …, Never …, Must …, Should …, Do not …) and a "Why" or "How to apply" section → wiki/conventions/<slug>.md
5. Entity — Overview of X, About X, What is X, Introduction to X → wiki/entities/<slug>.md
6. Concept — Concept:, Pattern:, Principle:, Strategy:, Design: heading → wiki/concepts/<slug>.md

If scan_text returns no candidates, tell the user: "No wiki-worthy sections detected in this source. Common reasons: the PR description is too short, or markers like 'Decision:' / 'Rationale:' are absent. You can promote manually by editing wiki/ pages and running git commit in the wiki repo."

Step 4 — present candidates for confirmation

Show each candidate to the user as a formatted block:

📄 Proposed wiki page
  Category: decisions
  Path:     wiki/decisions/2026-04-22-iceberg-cold-storage.md
  Title:    Why we chose Iceberg for cold storage
  Excerpt:  Decision: Use Iceberg tables for Snowflake cold storage tier.
            Rationale: Iceberg provides time-travel…

Then ask:

AskUserQuestion: "Promote [N] candidate(s) to the wiki?
  a) Promote all
  b) Choose individually
  c) Skip / cancel"

If "b" (choose individually): present each candidate and ask yes/no.

If "c": abort — print "Nothing promoted." and exit.

Step 5 — assemble WikiPage objects

For each confirmed candidate, construct the full page content:

# <title>

> Promoted from PR #<number> (<repo>) on <YYYY-MM-DD>
> Source: <PR URL>

<original source section, verbatim>

For decisions and incidents, include today's date in the filename. For other categories, the slug alone is enough (no date prefix).

Build WikiPage(path=candidate.suggested_path, title=..., content=...) for each confirmed candidate.

Step 6 — apply commit

Call apply_commit(wiki_repo_path, pages, message) from bin/promote_to_wiki.py.

The helper:

1. Aborts with a clear message if the wiki repo has uncommitted changes.
2. Fetches origin/main and fast-forward-pulls if the local branch is behind.
3. Writes each page file (creates parent dirs with pathlib).
4. Updates INDEX.md — inserts a new entry under the appropriate category header (idempotent: no-op if the path is already listed).
5. Stages the new files + INDEX.md, commits, and pushes to origin/main.

Commit message format: feat(wiki): promote <N> page(s) from PR #<number> (or feat(wiki): promote <N> page(s) from <source> for non-PR sources).

Step 7 — report back

After a successful commit, print:

✓ Promoted <N> page(s) to Artemis-xyz/data-hive-mind:
  - wiki/decisions/2026-04-22-iceberg-cold-storage.md
  …
Committed and pushed to main.

If push is not available (no remote configured — e.g. a local-only test clone), the commit still succeeds and the report says "Committed locally (no remote configured — push manually when ready)."

Output formats

Default: inline confirmation report (paths + commit SHA).

--dry-run flag: skip steps 5–7, print the candidate list and suggested paths without writing anything.

Error handling

Condition	Behavior
Wiki repo has dirty working tree	Abort with message listing dirty files
Wiki repo is behind origin/main and fast-forward fails	Abort — manual merge required
gh unavailable (no CLI)	Fall back to prompting the user to paste the PR body manually
Notion fetch fails	Warn and continue with PR text only
Page file already exists	Append a ## Update — YYYY-MM-DD section rather than clobbering

========================================

Lint mode — health checks

Status: implemented (Slice 5, TheClauu v0.3.29+)

Run structural health checks on the Artemis-xyz/data-hive-mind wiki. Designed for two contexts:

• Ad-hoc: engineer runs /theclauu:dhm lint in a session.
• Nightly CI: GitHub Actions cron in the data-hive-mind repo.

Invoking ad-hoc

/theclauu:dhm lint [--repo <path>]

Default wiki repo path: ../data-hive-mind/ relative to the current project. If the path is unknown, prompt the engineer once. Store the answer for the session.

Steps:

1. Run python bin/lint_wiki.py --repo <path> --format text (human output).
2. Print the findings table. Highlight [HIGH] findings in bold.
3. For each auto-fixable finding, ask: "Apply this fix now? (y/N)". Only apply after explicit confirmation — ad-hoc mode never auto-commits.
4. If any non-fixable finding exists, suggest: "Run /theclauu:dhm lint in CI to file these as Linear tickets automatically."

Invoking via CI

The nightly workflow (see install instructions in plugins/theclauu/docs/slice-5-install.md) runs bin/lint_wiki_ci.py, which:

1. Calls lint_wiki.lint(cwd) — pure Python, no network.
2. Files a Linear ticket for every high or medium severity finding.
3. Applies auto-fixes for auto_fixable=True findings in-place.
4. If any fixes were applied: commits them on branch dhm-lint/<YYYY-MM-DD> and opens a PR. Always branches — never commits direct-to-main — so every auto-fix gets a human eye before merge.

Checks

All checks run against the wiki/ subdirectory of the repo root.

1. Dead inter-page links (dead_links) — severity: high

Any ](wiki/<path>) or ](../<path>) in any page pointing to a non-existent file.

• Auto-fixable: yes — replaces ](<dead-target>) with ](TODO(dhm-lint): dead link — <target> not found).
• Linear ticket: yes (high severity).
• Rationale: broken links erode trust in the wiki faster than anything else. Fix immediately.

2. Orphan pages (orphans) — severity: medium

Any page in wiki/*/ with zero inbound links. Checks both inter-page links and INDEX.md entries.

• Auto-fixable: no — engineer decides whether to link or delete.
• Linear ticket: yes (medium severity).
• Exemptions: INDEX.md itself; top-level files like CLAUDE.md.

3. Stale pages (stale) — severity: medium

Any page in wiki/playbooks/, wiki/entities/, or wiki/conventions/ not touched (per git log -1 --format=%ct) in >90 days.

• Auto-fixable: no — engineer confirms whether content is still true.
• Linear ticket: yes (medium severity).
• Exemptions: wiki/decisions/ and wiki/postmortems/ are historical records — intentionally never flagged as stale.

4. Missing entity pages (missing_entities) — severity: low

A system name appears as H1/H2 (# SystemName) in ≥2 distinct pages but has no wiki/entities/<slug>.md.

• Auto-fixable: no — engineer writes the entity page.
• Linear ticket: yes (low severity — informational).
• Slug derivation: lowercase, spaces → hyphens, non-alphanumeric stripped.

5. INDEX.md integrity (index) — two sub-checks

5a. File not in INDEX.md — severity: low, auto-fixable. Adds - [<stem>](<rel-path>) under an ## Unlisted section at the bottom of INDEX.md.

5b. INDEX.md references non-existent file — severity: medium, not auto-fixable. Files a ticket asking why INDEX points to something gone.

Output format

Text (ad-hoc):

dhm-lint: 4 issue(s) found.

  [HIGH  ] dead_links           wiki/playbooks/on-call.md
             Dead link: '../entities/pagerduty.md' → resolved path does not exist [AUTO-FIXABLE]
             Fix: Replace '](../entities/pagerduty.md)' with '](TODO(dhm-lint): dead link …)'

  [MEDIUM] orphans              wiki/entities/deprecated-system.md
             Orphan page: no other page links here and INDEX.md doesn't list it.
  ...

JSON (CI): --format json emits a JSON array of Finding objects, one per issue. Consumed by lint_wiki_ci.py for programmatic processing.

Finding schema

{
  "check":        str,   // dead_links | orphans | stale | missing_entities | index
  "path":         str,   // repo-relative path of affected file
  "severity":     str,   // high | medium | low
  "message":      str,   // human-readable description
  "auto_fixable": bool,  // safe to apply in CI without engineer review
  "suggested_fix": str   // what to do (empty if not auto_fixable)
}

Threshold for branching vs. direct-to-main in CI

Always branch (dhm-lint/<YYYY-MM-DD>) — even for pure INDEX additions. Reasoning: predictability beats saving a click. Engineers can merge the PR in seconds; a surprise direct-to-main commit from a bot is confusing.

========================================

Conventions

• Wiki repo: Artemis-xyz/data-hive-mind
• Default branch: main
• Write mode: commit directly to main (single-contributor repo; feedback_data_hive_mind_direct_to_main.md). If another engineer becomes a regular contributor, this flips to PR-gated.
• Page conventions: see CLAUDE.md in the wiki.
• Never hand-edit wiki pages during normal work — use this skill. Typo fixes in PR review excepted.