← Market Analyst · c9

plan.md

c9. Project Docs — Analysis & Plan

Contents
  1. Audience & goal
  2. Current state audit
  3. Key gaps (answers to the prompt's questions)
  4. Sequencing vs c8 — split the work
  5. Out of scope

Clean up project documentation (README, agent docs, workflow instructions) in preparation for sharing with team members. Analysis snapshot taken 2026-08-20, while c8.agent-pivot is in flight.

Audience & goal

Team members (Tyler, Andrew, Jon, Devin, et al.) getting access to this repo for the first time. Two personas:

  1. Reader — opens the dashboard, needs to know how to interpret the data and its limitations. (README already serves this persona well.)
  2. Operator — wants to pull new calls, run extraction, ask the analysis agent questions. (This persona is badly underserved — see gaps.)

Plus a third, non-human persona: coding agents (Claude Code, Codex) landing in the repo, served by CLAUDE.md / AGENTS.md — currently inconsistent with each other.

Current state audit

ArtifactState
README.mdGood on data interpretation + limitations + /analyze. Missing setup, env, and any operational workflow. Pre-pivot framing (phase-1 PMF lens).
CLAUDE.mdCurrent and accurate (updated 2026-08-20, uncommitted). Missing: skills inventory, npm run fetch/upload:sagetap, newer pipeline scripts.
AGENTS.mdCorrupted — a find-replace copy of CLAUDE.md with "Claude"→"Codex", producing factual errors ("Codex API", "Codex Batches API" — extraction uses the Claude API). Also drifted: lacks the cycle conventions added to CLAUDE.md since.
.agents/skills/Stale copies of .claude/skills/ (extract SKILL.md differs; pickup skill missing). Duplicate-source-of-truth problem.
DEMO-SUMMARY.mdDemo artifact from March; cost figures dated; overlaps README. Stale at root.
TODO.mdCode-readability list from April; overlaps c8 Workstream D (architecture debt).
avoma-summary.txtScratch file from Feb 20. Stale at root.
inbox/Untracked working files (QControl positioning docs, .mhtml export). No documented purpose; needs triage before sharing.
briefs/, docs/Exist but appear nowhere in the architecture tree or any doc.
goals.mdDrives /analyze framing — still phase-1 PMF questions; will be rewritten by c8's use-case lens.
cycles/CYCLES.mdLists c3.oauth, c4.refinement, c7.avoma-notes as Active — likely dormant; none have PICKUP.md. Board reads inaccurately to a newcomer.
Skills/extract, /classify, /pickup exist but are documented nowhere outside their SKILL.md files; README mentions only /analyze.
Env/setupNo .env.example; ANTHROPIC_API_KEY + AVOMA_API_KEY requirements scattered across CLAUDE.md and memory; Node 22 requirement (--env-file) undocumented.

Key gaps (answers to the prompt's questions)

"Are the instructions for extracting new conversations clear?" — No.

The end-to-end path is: npm run fetch (Avoma → data/raw/ + sidecars) → triage (interactive classify) → npm run extract or extract:batch → npm run index → dashboard. Problems:

  • npm run fetch is documented nowhere — not in README, CLAUDE.md, AGENTS.md, or the /extract skill. Every doc starts from "transcripts in data/raw/" without saying how they get there. This is the single biggest gap.
  • upload:sagetap, generate, preview also undocumented.
  • The /extract skill covers triage→extract→index well, but only for Claude Code users; there's no human-readable runbook.
  • Undocumented pipeline scripts: avoma-notes.ts, backfill-speakers.ts, known-entities.ts.
  • Batch vs sequential tradeoffs (cost/time) live only in Claude's memory, not in the repo.

"What do we need?"

  • Setup section (README): clone, npm install (postinstall handles site), .env from a new .env.example, Node 22+.
  • Operations runbook ("adding new conversations"): the fetch→triage→extract→index→view loop, both the manual-command path and the /extract skill path, plus Sagetap upload.
  • Tool/skill tour: one section listing /analyze, /extract, /classify, /pickup with one-liners — the "agent tour."
  • A single source of truth for agent docs: fix AGENTS.md (either regenerate honestly from CLAUDE.md or make it a thin pointer), and resolve the .claude/skills vs .agents/skills duplication (symlink or delete .agents/).
  • Root hygiene: archive/relocate DEMO-SUMMARY.md, avoma-summary.txt, TODO.md (fold live items into c8), triage inbox/.
  • Accurate cycle board: park or close c3/c4/c7 so CYCLES.md tells the truth.

Sequencing vs c8 — split the work

c8 rewrites the extraction vocabularies, prompt, goals.md lens, and possibly schema/dashboard framing. Any doc describing what we extract and how to read it written now goes stale when c8 lands. But roughly two-thirds of c9 is pivot-independent. So:

Phase 1 — now (pivot-independent, safe during c8)

  1. Fix AGENTS.md (correct the Codex find-replace damage; align with CLAUDE.md or reduce to a pointer).
  2. Resolve .agents/skills vs .claude/skills duplication.
  3. Add .env.example + README Setup section (Node 22, both API keys, install).
  4. Document the full command surface (fetch, upload:sagetap, generate, preview) and missing pipeline scripts in CLAUDE.md/README.
  5. Root cleanup: archive DEMO-SUMMARY.md + avoma-summary.txt (e.g. docs/archive/), fold TODO.md into c8 workstream D or the cycle, triage inbox/.
  6. Cycle board hygiene: park (PICKUP.md) or close c3.oauth, c4.refinement, c7.avoma-notes.
  7. Commit the pending CLAUDE.md edits.

Phase 2 — after c8 completes (pivot-dependent)

  1. Rewrite README "How to Interpret the Data" for the phase-2 use-case lens (use-case validation, evidence kinds, relationship types) and refresh the limitations section.
  2. Write the operations runbook for adding new conversations (waiting on c8's new triage/import flow so we document it once).
  3. Update skill docs + README agent tour to match the post-pivot /analyze (new goals.md) and /extract behavior.
  4. Refresh cost/time benchmarks after the first phase-2 batch run.
  5. Final read-through as a new team member; then share.

Out of scope

  • Any pipeline/schema/site code changes (that's c8).
  • OAuth/dashboard access control (parked c3 — a prerequisite for hosting the dashboard for the team, but not for sharing the repo).

Qpoint Brand Style Guide