# IETF Draft Analyzer — Project Instructions

## What This Is

Python CLI tool (`ietf`) to track, categorize, rate, and map IETF Internet-Drafts on AI/agent topics. 361 drafts, 403 authors, 1,262 ideas, 12 gaps. Uses Claude for analysis, Ollama for embeddings, SQLite for storage.

## Key Paths

- Source: `src/ietf_analyzer/`
- Database: `data/drafts.db` (NOT `data/ietf_drafts.db`)
- Reports: `data/reports/`
- Blog series: `data/reports/blog-series/`
- Agent definitions: `.claude/agents/`
- Team prompt: `scripts/agent-team-prompt.md`
- Scripts: `scripts/`

## Development Journal

**Every agent and every session MUST log development milestones to `data/reports/dev-journal.md`.**

This journal serves two purposes:
1. Track progress across sessions so nothing gets lost
2. Source material for the meta blog post about using Claude agent teams to build this project

### What to Log

Append entries in this format:

```markdown
### [DATE] [AGENT/SESSION] — [SHORT TITLE]

**What**: [What was done — features built, analyses run, posts written]
**Why**: [The reasoning or decision behind it]
**Result**: [Outcome, key numbers, links to artifacts]
**Surprise**: [Optional — anything unexpected, a lesson learned, a tool limitation hit]
**Cost**: [Optional — API tokens, time taken, model used]
```

### Examples of What to Log

- Pipeline runs (how many drafts processed, cost, any failures)
- New features implemented (what, why, how it changed the analysis)
- Blog posts drafted or revised (key editorial decisions)
- Architectural decisions (why we structured something a certain way)
- Agent coordination moments (when one agent's output changed another's direction)
- Surprises in the data (unexpected findings that shifted the narrative)
- Tool/infra issues (things that broke, workarounds found)

### What NOT to Log

- Routine file reads or searches
- Minor formatting fixes
- Anything already captured in git commits

## Agent Team Conventions

When working as a team:

1. **Architect** designs the narrative arc and reviews everything for coherence
2. **Analyst** runs the pipeline, queries the DB, provides data packages
3. **Coder** implements new features following existing patterns (Click CLI, SQLite, rich output)
4. **Writer** produces the blog series from data packages and architectural guidance

**Always launch agents in parallel when possible.** If agents have independent tasks (e.g., Analyst querying data while Writer drafts from existing material, or Coder implementing features that don't depend on each other), spawn them concurrently in a single message rather than sequentially. Only run agents sequentially when one genuinely depends on another's output.

All agents should:
- Read `scripts/agent-team-prompt.md` for the full brief
- Log milestones to `data/reports/dev-journal.md`
- Write blog posts to `data/reports/blog-series/`
- Save reusable scripts to `scripts/`
- Follow existing code patterns (don't over-engineer)

## Blog Series

7 posts planned in `data/reports/blog-series/` (01 through 07), plus:
- **Post 8: "Agents Building the Agent Analysis"** — Meta post about using Claude Code agent teams to analyze and write about IETF agent standards. The dev-journal.md is the source material for this post.

## Code Conventions

- CLI: Click commands in `cli.py` with `@click.option()` decorators
- DB: Tables in `db.py` `ensure_tables()`, queries as methods on `DraftDB`
- Reports: Report types in `reports.py` `generate_report()`
- Always cache Claude API calls via `llm_cache` table
- Use `rich` for console output
- Save multi-step workflows as scripts in `scripts/`

## Current Status (2026-03-03)

- v0.2.0, 361 drafts (101 new, unprocessed)
- 101 new drafts need: analyze, authors, ideas, embed, gaps
- Blog series: planned, not yet written
- Agent team: defined in `.claude/agents/`, ready to launch