flonat-research 0.1.0

package/skills/shared/skill-index.md

@@ -0,0 +1,240 @@
+# Skill Index
+
+> Compact discovery table for all skills. Scan this when checking for duplicates,
+> answering "what skills do I have for X?", or deciding where a new skill fits.
+
+## By Category
+
+### Ideation (3)
+
+| Skill | Purpose |
+|-------|---------|
+| `interview-me` | Interactive interview to formalise a research idea into a structured spec |
+| `devils-advocate` | Multi-turn debate to challenge assumptions and stress-test arguments |
+| `multi-perspective` | Parallel agents with distinct disciplinary lenses explore a question |
+| `scout-audit` | Batch novelty checks with venue and idea iteration |
+| `scout-discover` | Topic discovery and idea generation via Scout CLI |
+| `scout-evaluate` | Novelty scoring and idea ranking via Scout CLI |
+| `scout-develop` | Iterative idea development and Lopez-Lira refinement via Scout CLI |
+| `scout-position` | Venue suggestion, framing, and acceptance assessment via Scout CLI |
+| `atlas-coherence` | Map portfolio as a network: clusters, bridges, orphans, sequencing |
+| `atlas-novelty` | Score atlas topics by novelty via batch Scout checks |
+| `interdisciplinary-bridge` | Import concepts from adjacent fields to solve open problems |
+| `future-research-agenda` | Generate provocative, fundable future research directions |
+
+### Literature (9)
+
+| Skill | Purpose |
+|-------|---------|
+| `literature` | Academic search, citation verification, .bib management, OpenAlex API |
+| `split-pdf` | Deep-read papers via 4-page chunks with structured notes |
+| `gather-readings` | Copy PDFs from Zotero into project articles/ folder |
+| `theory-mapper` | Map theoretical landscape across a corpus of papers |
+| `method-audit` | Compare data collection methods and spot biases |
+| `evolution-timeline` | Chronological narrative of field evolution |
+| `quote-mining` | Extract exact quotes with page numbers and argument mapping |
+| `weakness-scanner` | Find weakest arguments and logical flaws across a literature |
+| `replication-audit` | Audit replication status of key findings |
+
+### Writing (1)
+
+| Skill | Purpose |
+|-------|---------|
+| `proofread` | 7-category LaTeX proofreading scorecard (report only) |
+| `claim-audit` | Verify cited claims against actual source papers |
+| `voice-analyzer` | Analyze writing samples to create a portable voice profile (VOICE.md) |
+| `voice-editor` | Edit content to match a voice profile (6-pass workflow, 4 editing modes) |
+| `journal-voice` | Extract journal writing patterns and conventions into JOURNAL-VOICE.md |
+| `review-response` | Systematic reviewer response drafting with classification, strategy, and tone checks |
+
+### Presentation (8)
+
+| Skill | Purpose |
+|-------|---------|
+| `beamer-deck` | Rhetoric-driven Beamer slides with multi-agent review |
+| `quarto-deck` | Reveal.js HTML presentations (teaching, informal talks) |
+| `quarto-course` | Quarto course websites with slides and exercises |
+| `project-deck` | Status decks for supervisor meetings and handoffs |
+| `insights-deck` | Claude Code usage insights as a Beamer presentation |
+| `latex-posters` | Research posters in LaTeX (beamerposter, tikzposter, baposter) |
+| `translate-to-quarto` | Translate Beamer LaTeX slides to Quarto RevealJS |
+| `pptx` | Create, read, edit, or manipulate PowerPoint files |
+
+### LaTeX & Bibliography (10)
+
+| Skill | Purpose |
+|-------|---------|
+| `latex` | Basic LaTeX compilation with latexmk |
+| `latex-autofix` | **Default compiler** — auto-fixes errors, citation audit on success |
+| `latex-health-check` | Compile all projects, auto-fix, check cross-project consistency |
+| `latex-template` | Compare preamble against working paper template (report + apply) |
+| `bib-validate` | Cross-reference \cite{} keys against .bib files (report only) |
+| `bib-filter` | Filter a .bib file to only entries actually cited in a .tex project |
+| `bib-parse` | Extract citations from a PDF and generate a validated `.bib` file |
+| `bib-coverage` | Compare a project .bib against a Zotero collection to find uncited papers |
+| `bib-migrate` | Compare Paperpile and Zotero libraries to find items missing from each |
+| `latex-scaffold` | Convert Markdown draft into buildable LaTeX project (md→tex) |
+
+### Submission (5)
+
+| Skill | Purpose |
+|-------|---------|
+| `pre-submission-report` | All quality checks in one dated report |
+| `retarget-journal` | Switch paper to different journal (rename, reformat, rekey) |
+| `process-reviews` | Referee comments PDF into tracking files |
+| `synthesise-reviews` | Synthesise parallel review reports into a prioritised revision plan |
+| `brief-compliance-check` | Check LaTeX submission against assessment brief (deliverables, word limits, required files) |
+
+### Project Setup & Session (17)
+
+| Skill | Purpose |
+|-------|---------|
+| `init-project-research` | Full project scaffold (interview, git, Overleaf, vault) |
+| `init-project-course` | Course/module folder scaffold |
+| `init-project-light` | Lightweight scaffold (CLAUDE.md only, no git/vault) |
+| `init-project-orchestration` | Add project agents, commands, and planning to a research project |
+| `project-safety` | Safety rules and folder structures to prevent data loss |
+| `session-log` | Timestamped progress logs for session continuity |
+| `general-session-recap` | End-of-session checklist for any project type |
+| `research-session-recap` | Research session close with atlas/vault checks |
+| `update-focus` | Structured update to current-focus.md |
+| `context-status` | On-demand session health check |
+| `save-context` | Save information to context library files |
+| `task-management` | Daily planning, weekly reviews, meeting actions, vault |
+| `ideas` | Capture improvement ideas for the infrastructure |
+| `consolidate-memory` | Prune, merge, and abstract MEMORY.md entries |
+| `update-project-doc` | Update a project's own docs to reflect current state |
+| `vault sync` | Sync project state to context library and vault |
+| `email-digest` | Email digest from Gmail |
+| `decision-toolkit` | Structured decision-making for methodology, venue, or framework choices |
+
+### Code & Analysis (8)
+
+| Skill | Purpose |
+|-------|---------|
+| `code-review` | 11-category scorecard for R/Python scripts (report only) |
+| `code-archaeology` | Review and document old code, data, and analysis files |
+| `pipeline-manifest` | Map scripts to inputs, outputs, and paper figures/tables |
+| `python-env` | Python environment management (enforces uv) |
+| `audit-project-research` | Audit project against init-project-research template |
+| `audit-project-course` | Audit course folder against init-project-course template |
+| `webapp-testing` | Playwright-based web app testing with server lifecycle management. *From Anthropic.* |
+| `frontend-design` | Distinctive, production-grade frontend interfaces. *From Anthropic.* |
+
+### Experimental & Data (11)
+
+| Skill | Purpose |
+|-------|---------|
+| `data-analysis` | End-to-end analysis pipeline (EDA, estimation, publication output) across R/Python/Stata/Julia |
+| `computational-experiments` | Scaffold, run, and publish computational research experiments (algorithm skeletons, config-driven sweeps, seed-deterministic runners, publication figures) |
+| `experiment-design` | Experimental and survey design: power analysis, PAP, QSF parsing, survey construction |
+| `causal-design` | Identification strategy design and audit (DiD/IV/RDD/SC/event study) |
+| `synthetic-data` | Generate structurally realistic synthetic datasets for pilot testing and power analysis |
+| `replication-package` | Replication package assembly, anonymization, and audit (replaces export-project-clean/anon) |
+| `econ-data` | Fetch economic data from FRED, World Bank, Eurostat, ECB, OECD, and EEX APIs |
+| `econ-plots` | Economics-standard ggplot2 plots: coefficient, binscatter, RDD, decomposition |
+| `r-econometrics` | R regression and econometrics: OLS, IV, panel, RDD, robust SEs |
+| `event-studies` | DiD and event study implementation in R (TWFE vs modern estimators) |
+| `code-paper-audit` | Systematic 6-phase code-paper consistency audit |
+
+### Infrastructure (30)
+
+| Skill | Purpose |
+|-------|---------|
+| `learn` | Extract session knowledge into a new persistent skill |
+| `creation-guard` | Pre-flight duplicate check before creating new skills/agents |
+| `lessons-learned` | Structured post-mortem for incidents and stuck sessions |
+| `system-audit` | Parallel audits across skills, hooks, agents, rules, docs |
+| `atlas-review` | Full audit of all topics across 4 systems |
+| `atlas-deploy` | Compile atlas.json from topic files, commit, and deploy atlas web app to Fly.io |
+| `rename-project-research` | Rename an Atlas topic slug across all systems |
+| `sync-atlas` | Sync between Atlas topic files and vault |
+| `atlas-drift-check` | Verify Atlas schema, vault sync, disk paths, and frontmatter consistency |
+| `scout-drift-check` | Check CLI-web parity, route coverage, and taxonomy consistency in Scout |
+| `sync-repo` | Sync docs with system state for atlas, scout, refpile, or private repos |
+| `sync-public-repo` | Sync private infrastructure to the public repo (claude-research) |
+| `sync-public-review` | Interactive review and editing of public sync allowlists |
+| `sync-santi-repo` | Regenerate the santi-repo starter kit from private rules |
+| `sync-resources` | Pull latest from cloned resource repos |
+| `sync-permissions` | Sync global permissions into projects |
+| `full-commit` | Commit and push all 8 global repos with leak guard |
+| `publish` | Full publication pipeline: sync, bump, commit, tag, publish |
+| `refpile-development` | Update and manage RefPile development topic documents |
+| `skill-creator` | Create, iterate, and benchmark skills with eval viewer. *From Anthropic.* |
+| `skill-health` | Skill health dashboard: invocation counts, success rates, health status |
+| `mcp-builder` | Guide for creating MCP servers (Python/FastMCP or TypeScript). *From Anthropic.* |
+| `external-audit` | External LLM audit of any repo (atlas, scout, refpile, private, public, santi) |
+| `audit-doc` | Documentation quality audit for any repo (atlas, scout, refpile, private, public, santi) |
+| `docs-review` | Cross-cutting doc review: count consistency, component coverage, stale refs, public-private sync, user manual |
+| `machine-audit` | Audit machine environment (Homebrew, dotfiles, credentials, dev tools, nested repos, MCP) |
+| `machine-review` | Holistic review of machine setup from snapshots: missing tools, redundant apps, cross-machine parity |
+| `radar` | Search the web for Claude Code updates, AI workflow patterns, and MCP ecosystem news |
+| `radar-integrate` | Convert saved radar tips into infrastructure changes |
+| `wire-shared-package` | Wire a shared Python package as an editable dependency across projects |
+
+### Document Formats (3)
+
+| Skill | Purpose |
+|-------|---------|
+| `docx` | Create, read, edit, or manipulate Word documents |
+| `pdf` | Read, extract, combine, split, rotate, watermark PDF files |
+| `xlsx` | Create, read, edit spreadsheets (.xlsx, .csv, .tsv) |
+
+### Meetings (11)
+
+| Skill | Purpose |
+|-------|---------|
+| `minutes-record` | Start or stop recording a meeting, call, or voice memo |
+| `minutes-debrief` | Post-meeting debrief — compare outcomes to prep intentions |
+| `minutes-prep` | Interactive meeting preparation with relationship briefs |
+| `minutes-recap` | Daily digest of meetings — decisions, action items, themes |
+| `minutes-weekly` | Weekly meeting synthesis — themes, decision arcs, stale commitments |
+| `minutes-search` | Search past meeting transcripts and voice memos |
+| `minutes-list` | List recent meetings and voice memos |
+| `minutes-note` | Add timestamped notes during or after a recording |
+| `minutes-verify` | Verify minutes setup — model, mic, directories |
+| `minutes-setup` | Guided first-time setup for minutes |
+| `minutes-cleanup` | Manage old recordings — archive, delete, disk space |
+
+---
+
+**Total: 139 skills across 12 categories.**
+
+---
+
+## Shared References (not skills — cross-cutting protocols)
+
+Files in `skills/shared/` that multiple skills and agents reference. These are not invocable skills — they are guidance documents read on demand.
+
+### Methodological Protocols
+
+| File | Purpose | Used by |
+|------|---------|---------|
+| `escalation-protocol.md` | 4-level methodological pushback (Probe → Explain → Challenge → Flag) | paper-critic, referee2-reviewer, domain-reviewer, data-analysis, causal-design, experiment-design |
+| `method-probing-questions.md` | Mandatory pre-analysis questions by method (12 paradigms) | data-analysis, causal-design, experiment-design, referee2-reviewer, domain-reviewer |
+| `distribution-diagnostics.md` | DV distribution checks + model selection decision tree | data-analysis, referee2-reviewer, domain-reviewer |
+| `engagement-stratified-sampling.md` | Engagement-tier sampling for social media data | data-analysis, experiment-design, referee2-reviewer |
+| `intercoder-reliability.md` | Per-category reliability + LLM annotation validation | data-analysis, experiment-design, referee2-reviewer, domain-reviewer |
+
+### Skill Architecture
+
+| File | Purpose |
+|------|---------|
+| `quality-scoring.md` | Shared scoring framework for quality reports |
+| `progressive-disclosure.md` | Pattern for splitting large skills into core + references |
+| `skill-design-patterns.md` | Structural patterns for skill architecture |
+| `rhetoric-principles.md` | Presentation rhetoric for deck skills |
+| `multi-language-conventions.md` | R/Python/Stata/Julia conventions for analysis skills |
+| `reference-resolution.md` | Logic for resolving Zotero collections and topic references |
+| `research-quality-rubric.md` | Research quality rubric for review agents |
+| `council-protocol.md` | Multi-model council deliberation protocol |
+| `external-audit-protocol.md` | Protocol for external LLM audits |
+| `paid-api-safety.md` | Cost guardrails for paid API calls |
+| `mcp-degradation.md` | Graceful degradation when MCP tools are unavailable |
+| `project-documentation.md` | Project documentation conventions (index) |
+| `project-documentation-content.md` | Content conventions (README, manual, architecture, deploy) |
+| `project-documentation-format.md` | Format conventions (ASCII, LaTeX, Beamer, public variants) |
+| `system-documentation.md` | System documentation conventions |
+| `tikz-rules.md` | TikZ diagram conventions |
+| `palettes.md` | Colour palettes for visualisations |
+| `skill-index.md` | This file |

package/skills/shared/system-documentation.md

@@ -0,0 +1,334 @@
+# System Documentation Conventions
+
+> Formatting, structure, and style conventions for Task Management infrastructure documentation: CLAUDE.md, SKILL.md, rules, component catalogues (`docs/`), and shared resources.
+>
+> Companion to `project-documentation.md` (which covers outward-facing docs like READMEs, user manuals, and architecture references).
+
+## Document Types and Purposes
+
+| Document | Audience | Purpose | Tone |
+|----------|----------|---------|------|
+| `CLAUDE.md` | Claude (AI) | Session instructions — what to do and how | Imperative, terse |
+| `README.md` | Human developers | Project overview, quick start, navigation | Friendly, scannable |
+| `SKILL.md` | Claude (AI) | Step-by-step workflow protocol | Imperative, procedural |
+| `docs/*.md` | Human + AI | Detailed reference material | Neutral, thorough |
+| `user-manual.md` | End users | Feature docs, how-to guides | Approachable, example-driven |
+| `architecture.md` | Maintainers | Technical internals, data flow, design decisions | Precise, factual |
+
+---
+
+## Markdown Formatting
+
+### Header Hierarchy
+
+```markdown
+# Document Title        ← one per file, matches the file's purpose
+## Major Section        ← top-level topic divisions
+### Subsection          ← details within a section
+#### Rarely deeper      ← only for deeply nested reference material
+```
+
+Never skip levels (e.g., `#` → `###`). Use `##` as the primary structural unit — most navigation (TOCs, anchors, `/help` slugs) keys off `##` headings.
+
+### Opening Context Block
+
+Every document starts with a title, then a blockquote summarising what the file is and who it's for:
+
+```markdown
+# Document Title
+
+> One-liner explaining what this document covers and when to read it.
+```
+
+For reference files shared across skills, add a second line noting which skills consume it:
+
+```markdown
+> Shared reference for `/skill-a`, `/skill-b`, and `/skill-c`.
+```
+
+### Tables
+
+Use tables for structured reference material — indices, mappings, rubrics, configuration:
+
+```markdown
+| Column A | Column B | Column C |
+|----------|----------|----------|
+| value    | value    | value    |
+```
+
+- Left-align text columns, right-align numeric columns
+- Bold header-row values only when the table is a rubric or decision matrix
+- Prefer tables over bullet lists when items have 2+ parallel attributes
+- Keep cell content concise — one line per cell, no paragraphs inside cells
+
+### Code Blocks
+
+Always use fenced code blocks with language tags:
+
+````markdown
+```python
+def example():
+    pass
+```
+
+```bash
+uv run python script.py
+```
+
+```latex
+\section{Introduction}
+```
+
+```yaml
+name: skill-name
+description: "What it does"
+```
+````
+
+For inline code: use backticks for file names (`` `config.py` ``), class names (`` `Settings` ``), method names (`` `discover_topics()` ``), env vars (`` `OPENROUTER_API_KEY` ``), and CLI commands (`` `uv run python` ``).
+
+### Lists
+
+- **Numbered lists** for sequential steps (protocols, workflows, order of operations)
+- **Bullet lists** for non-sequential items (features, alternatives, notes)
+- **Nested bullets** for elaboration — one level deep only; if deeper nesting is needed, restructure as a subsection
+- **Checklists** (`- [ ]`) only in plans and session logs, never in reference docs
+
+### Cross-References
+
+```markdown
+Full details: [`docs/architecture.md`](docs/architecture.md)
+See [`references/drift-checks.md`](references/drift-checks.md)
+```
+
+Always use relative paths. Always include both the display text (the file name) and the link. For skills, use the forward-slash notation: `/skill-name`.
+
+### Horizontal Rules
+
+Use `---` to separate major conceptual blocks within a section. Do not use between every subsection — only between distinct topics or phases.
+
+---
+
+## Document Structure Patterns
+
+### CLAUDE.md (AI Context File)
+
+```markdown
+# Claude Context for [Project Name]
+
+> One-liner about the project.
+
+## [Safety/Protection Rules]     ← always first if present
+## File Structure                ← compact tree, annotated
+## Conventions                   ← project-specific rules
+## [Domain-Specific Sections]    ← what Claude needs to know
+## Session Continuity            ← pointers to .context/, log/
+```
+
+**Key constraints:**
+- **Max 200 lines.** Extract anything longer than 15 lines of reference material to `docs/` with a one-line pointer (see `lean-claude-md` rule).
+- **Instructions, not knowledge.** CLAUDE.md tells Claude what to do and where to look — it doesn't store the knowledge itself.
+- **Pointer pattern:** `Full guidelines: [\`docs/file.md\`](docs/file.md)`
+
+### README.md (Human Overview)
+
+```markdown
+# Project Name
+
+Brief description (1-3 sentences).
+
+## What It Does / Overview       ← the "why" and "what"
+## Getting Started / Setup       ← quick start for new users
+## Project Structure             ← compact file tree
+## Documentation                 ← links to docs/ files
+## [Key Sections]                ← project-specific
+```
+
+**Key constraints:**
+- **Max 150 lines** for most projects (300 for the Task Management root).
+- Overlap with `user-manual.md` or `docs/` should be a summary + link, not duplication.
+- Quick start instructions must be copy-pasteable.
+
+### SKILL.md (Workflow Protocol)
+
+```yaml
+---
+name: skill-name
+description: "One-line description of what the skill does."
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash(pattern*), AskUserQuestion
+argument-hint: <topic> [--flag]
+---
+```
+
+```markdown
+# Skill Title
+
+> Audit sentence explaining what this skill does and when to use it.
+
+## When to Use
+## When NOT to Use
+## Protocol                      ← numbered steps
+### Step 1: [Action]
+### Step 2: [Action]
+## [Reference Tables]
+## Cross-References              ← links to related skills
+```
+
+**Key constraints:**
+- **Max 300 lines.** Extract long reference tables, rubrics, or examples to `references/` with a pointer.
+- Steps are imperative: "Read the file", "Compare against", "Flag mismatches".
+- Include a `When NOT to Use` section to prevent misapplication.
+
+### Docs Files (Reference Material)
+
+No strict template — structure follows the content. But follow these conventions:
+
+- Start with `# Title` + blockquote context
+- Use `##` sections as the main structural unit
+- Include a navigation aid for long files (table of contents or section index at the top)
+- Architecture docs should include ASCII diagrams for data flow and system overview
+- API/configuration docs should use tables for parameter lists
+
+### Component Catalogues (`docs/skills.md`, `docs/hooks.md`, etc.)
+
+The Task Management `docs/` folder uses a consistent pattern for documenting collections of infrastructure components (skills, hooks, agents, rules, resources, scripts).
+
+```markdown
+# Component Type (plural)
+
+> {count} {component type} + one-sentence description of what they are.
+
+Brief intro paragraph: what the component is, where it lives, how it's configured.
+
+## Overview
+
+| Component | Category | Description |
+|-----------|----------|-------------|
+| `name`    | ...      | ...         |
+
+---
+
+## Component Details
+
+### 1. Component Name (optional metadata)
+
+What it does, when it applies, and how it works.
+```
+
+**Conventions:**
+- **Count in blockquote:** Every catalogue opens with the actual count. This count must match reality — `/sync-repo private` propagates count changes across files.
+- **Overview table first:** A compact table listing every item before any details. Columns vary by component type (see below).
+- **Numbered detail sections:** Each component gets a `###` subsection.
+- **Cross-file count consistency:** Counts appear in CLAUDE.md, README.md, `docs/system.md`, and the catalogue file. All must agree.
+
+**Catalogue-specific columns:**
+
+| Catalogue | Required columns |
+|-----------|-----------------|
+| Skills (`docs/skills.md`) | Skill, Category, Description |
+| Hooks (`docs/hooks.md`) | Hook, Event, Matcher, Script, What it does |
+| Agents (`docs/agents.md`) | Agent, Purpose |
+| Rules (`docs/rules.md`) | Rule, File, What it does |
+| Resources (`docs/resources.md`) | Category, Author, Repo, What it provides |
+
+### System Overview (`docs/system.md`)
+
+Not a component catalogue but an architectural overview of the entire Task Management system. Uses:
+
+- ASCII diagram showing the full system layout
+- Numbered `##` sections for each major subsystem (context library, skills, hooks, etc.)
+- Component count references that stay in sync with the individual catalogues
+- File structure table mapping paths to purposes
+
+---
+
+## Writing Conventions
+
+### Voice and Tone
+
+| Context | Voice | Example |
+|---------|-------|---------|
+| CLAUDE.md, SKILL.md, rules | Imperative | "Read the config file. Compare against the source." |
+| README.md, user-manual | Second person | "You can configure the model with `--model`." |
+| Architecture docs | Third person, present tense | "The orchestrator wires the data source to the LLM service." |
+| Session logs | Past tense, first person plural | "We implemented the validation script." |
+
+### Conciseness
+
+- Lead with the information, not the setup. Not "It should be noted that X" — just "X".
+- One idea per paragraph. If a paragraph covers two distinct points, split it.
+- Prefer tables over prose for structured information (3+ items with parallel attributes).
+- Delete filler: "basically", "simply", "just", "in order to", "it is important to note that".
+
+### Terminology
+
+Use these terms consistently across all documentation:
+
+| Term | Meaning | Not |
+|------|---------|-----|
+| Skill | Reusable workflow definition in `skills/` | "command", "script", "macro" |
+| Agent | Independent Claude instance with fresh context | "sub-agent", "worker" |
+| Hook | Automated script triggered by Claude Code events | "trigger", "listener" |
+| Rule | Behavioural constraint, auto-loaded every session | "policy", "guideline" |
+| Resource | Cloned external repo in `resources/` | "dependency", "library" |
+| Workflow | A sequence of steps within a skill | "process", "pipeline" (unless actually a data pipeline) |
+| Drift | Documentation claiming something that code no longer supports | "stale", "outdated" (less precise) |
+
+### Numbers and Counts
+
+- Spell out numbers one through nine in prose; use digits for 10+.
+- Always verify counts by listing actual files — never trust cached numbers in docs.
+- When a count appears in multiple files, update all of them (or use `/sync-repo private`).
+
+### File Paths
+
+- Use backtick-quoted relative paths: `` `src/services/llm.py` ``
+- In file trees, use the standard tree notation:
+
+```
+project/
+├── src/
+│   ├── main.py
+│   └── config.py
+├── docs/
+│   └── architecture.md
+└── README.md
+```
+
+- Annotate tree entries with brief descriptions when the name isn't self-explanatory:
+
+```
+├── bootstrap.py         # Shared init logic — used by CLI + web
+├── config.py            # Settings + re-exports from llm-council
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|--------------|-------------|-----|
+| Duplicating content across files | Goes stale independently, contradicts itself | Keep detail in one file, use pointers elsewhere |
+| Hardcoding counts in prose | Requires manual updates across 8+ files | Use verifiable counts or link to the source |
+| Writing CLAUDE.md as a knowledge base | Burns tokens every session | Extract to `docs/`, leave a one-line pointer |
+| Paragraphs inside table cells | Unreadable, breaks rendering | Keep cells to one line; use a subsection instead |
+| Deep nesting (4+ bullet levels) | Cognitive overload, hard to scan | Restructure as subsections or a table |
+| Mixing imperative and descriptive voice | Confusing — is this an instruction or a description? | Match voice to document type (see table above) |
+| Undated session-specific content in reference docs | Reference docs should be timeless | Session details go in `log/`, not `docs/` |
+
+---
+
+## Checklist for New Documents
+
+Before considering a document complete:
+
+1. **Opening context block** — title + blockquote describing purpose and audience
+2. **Header hierarchy** — no skipped levels, `##` as primary structure
+3. **Tables for structured data** — not bullet-list parades
+4. **Code blocks tagged** — every fenced block has a language identifier
+5. **Cross-references linked** — related files and skills linked, not just named
+6. **Within line limits** — CLAUDE.md < 200, README < 150, SKILL.md < 300
+7. **No duplication** — information lives in one canonical place with pointers
+8. **Terminology matches** — uses standard terms from the terminology table
+9. **Voice matches document type** — imperative for instructions, descriptive for reference
+10. **File paths are relative** — no absolute paths in documentation