governance-autoresearch

name	governance-autoresearch
description	Autoresearch loop for governance files. Researches latest X discourse on each governance topic, proposes ONE atomic improvement per file, validates it, keeps or discards. Use when the user asks to improve, update, or evolve the governance framework using latest community insights.

Governance Autoresearch Skill

Overview

Adapts Karpathy's autoresearch pattern to governance file improvement:

• Research each file's topics on X (last 7 days)
• Cross-reference with bookmarks data (if available in X-Bookmarks Import/)
• Propose ONE atomic change per file
• Validate structure and SSOT consistency
• Keep if it improves the file, discard if not
• Commit each kept change with experiment: prefix

Prerequisites

• X_BEARER_TOKEN in .env
• Python 3.10+
• Bookmarks import data (optional, in X-Bookmarks Import/)

Workflow — Execute These Steps Per File

Step 0: Get Research Context

Run the research script for the target file:

python3 "X-Bookmarks Import/skills/governance-autoresearch/scripts/governance_research.py" "<file_path>"

This outputs JSON with:

• Top X posts about the file's topics (engagement-ranked)
• External links being shared
• File summary for context

Step 1: Read the File

Read the full governance file. Note:

• Current structure and sections
• YAML frontmatter (doc_type, ssot_owner)
• Key policies, rules, or patterns defined

Step 2: Cross-Reference Bookmarks (if available)

Check X-Bookmarks Import/data/articles-batch-1.md, data/articles-batch-2.md, data/github-repos.md, data/other-sources.md for content relevant to this file's domain. Key sources:

Bookmark Content	Relevant To
Claude Code Skills (Anthropic)	skill-standards, platform-adapters
.claude/ folder anatomy	settings, context-retrieval
Autoresearch / self-improving	automation loops, nightly-compound
Paperclip (AI company)	workflow orchestration, subagents
EurekaClaw (memory system)	context-retrieval, SSOT
evals-skills (hamelsmu)	testing, playbooks
project-skill-audit	skill-standards, repo-discovery
chrome-cdp-skill	skill-standards, platform-adapters
Self-learning agents (Cursor)	principles, AGENTS.md
SOTA memory system	context-retrieval, sources-of-truth

Step 3: Propose ONE Atomic Change

Based on research findings, propose exactly ONE change. Types of valid changes:

1. Add a new section — a concept the community is converging on that the file doesn't cover
2. Strengthen an existing rule — add specificity based on real-world patterns
3. Add a reference/link — point to a new tool, pattern, or standard
4. Update terminology — align with current ecosystem language
5. Add a gotcha/anti-pattern — something the community has learned the hard way

Anti-patterns (DO NOT do these):

• Do NOT rewrite entire files
• Do NOT change SSOT owners or frontmatter without explicit approval
• Do NOT add speculative features — only things with community evidence
• Do NOT duplicate content already in another governance file
• Do NOT remove existing rules without evidence they're harmful
• Do NOT add content unrelated to the file's stated scope

Step 4: Validate

Before applying, check:

1. Structure preserved — YAML frontmatter intact, heading hierarchy maintained
2. SSOT consistency — no contradictions with AGENTS.md or other governance files
3. No duplication — content doesn't exist elsewhere in the governance pack
4. Evidence-backed — change is supported by X research or bookmarks data
5. Minimal diff — smallest change that captures the insight

Run validation if available:

python3 scripts/check_governance_core/main.py

Step 5: Apply or Discard

• If validation passes: apply the change using Edit tool
• If validation fails: discard and record why
• Record the outcome either way

Step 6: Report

For each file, output:

FILE: <path>
STATUS: KEPT | DISCARDED
CHANGE: <one-line description>
EVIDENCE: <X post URL or bookmark reference>
REASON: <why this improves the governance framework>

Running the Full Loop

To process all governance files sequentially:

1. Get the file list:

python3 "X-Bookmarks Import/skills/governance-autoresearch/scripts/governance_research.py" --list

2. For each file, execute Steps 0-6 above.

3. After all files, run full validation:

python3 scripts/check_governance_core/main.py

Scoring (How to Judge Quality)

A change is worth keeping if it meets ALL of:

• Adds genuinely new information not derivable from existing docs
• Supported by 2+ X posts or 1 high-engagement post (>100 likes)
• Fits the file's existing scope and doc_type
• Does not weaken existing rules
• Passes structural validation

Rate Limit Awareness

• X API recent search: 180 requests / 15 minutes
• Each file uses 2-3 search queries
• Full loop (~27 files) uses ~80 queries — well within limits
• If rate-limited, wait and resume from the last file