analyst-playbook

Preamble (run first)

PLAN MODE EXCEPTION — ALWAYS RUN: this block only reads state and writes to ~/.analyst-kit/.

_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
if [ ! -x "$_AK/bin/analyst-kit-preamble" ]; then
  for d in ~/.claude/skills/analyst-kit-core .claude/skills/analyst-kit-core ~/.codex/skills/analyst-kit-core .codex/skills/analyst-kit-core; do
    [ -x "$d/bin/analyst-kit-preamble" ] && _AK="$d" && break
  done
  [ -x "$_AK/bin/analyst-kit-preamble" ] || _AK="$(find ~/.claude/plugins -maxdepth 6 -type d -name analyst-kit-core 2>/dev/null | head -1)"
  [ -n "$_AK" ] && { mkdir -p ~/.analyst-kit; printf '%s' "$_AK" > ~/.analyst-kit/core-path; } || true
fi
[ -x "$_AK/bin/analyst-kit-preamble" ] && "$_AK/bin/analyst-kit-preamble" --skill analyst-playbook 2>/dev/null || echo "AK_CORE: not found (continue without runtime)"

Read the echoed state and act. Skip ALL bullets below if DEDUP: yes or AK_CORE: not found:

• DISABLED: yes → this skill is turned off because a required API key isn't configured. Do not run it. Tell the user it's off, name the missing key (see MISSING_KEYS), and offer to enable it — either they give you the key now (store it with "$_AK/bin/analyst-kit-setup" set-key <KEY> <value>, which re-enables the skill) or they say "set up analyst-kit" for full setup. Then stop; do not attempt the skill's work.
• First run — ONBOARDED: no → orient the user once, then run "$_AK/bin/analyst-kit-setup" finish (this covers the telemetry notice, so skip the TEL_PROMPTED bullet this turn):
  1. Data home — tell the user Analyst Kit keeps config, API keys, local usage analytics, and a learnings log together in one folder (default ~/.analyst-kit); offer to move it with "$_AK/bin/analyst-kit-setup" home <dir>.
  2. Telemetry (a notice, not a question) — usage telemetry is on by default: only skill name, duration, outcome, and version, tagged with a random per-machine device id, never repo names, paths, tickers, or content; opt out anytime by asking to turn Analyst Kit telemetry off.
  3. Offer full setup — ask if they'd like to configure API keys for all skills now. If yes, Read "$_AK/references/intro.md" and follow it. If no, continue — you'll ask for a key only when a skill needs one.
  4. Run "$_AK/bin/analyst-kit-setup" finish.
• User asks to set up Analyst Kit at any time (e.g. "set up analyst-kit", "help me set up Analyst Kit", "configure all skills") → Read "$_AK/references/intro.md" and follow it end to end: data home, telemetry, every skill's keys, and enabling/disabling each.
• TEL_PROMPTED: no (returning user) → give the telemetry notice once, then run "$_AK/bin/analyst-kit-setup" ack-telemetry.
• If the user asks to turn telemetry off (now or anytime): before flipping it, make a sincere case once — telemetry is what tells the maintainers which skills break, which run slow, and where users get stuck, so keeping it on directly improves their experience; it never includes their data. Offer "$_AK/bin/analyst-kit-config" set telemetry anonymous (drops the device id) as a middle ground. If they still want out, run "$_AK/bin/analyst-kit-config" set telemetry off immediately and without further argument.
• Before running any script that needs an API key: source both the data home's .env and the current directory's .env into the shell so scripts can read stored keys: set -a; [ -f "$AK_HOME/.env" ] && . "$AK_HOME/.env"; [ -f "./.env" ] && . "./.env"; set +a (where $AK_HOME is the path printed on the AK_HOME: line above). Full lookup order — always check these before concluding a key is missing or asking the user:
  1. current shell environment
  2. $AK_HOME/.env (keys stored by analyst-kit-setup)
  3. .env in the current working directory Never ask the user for a key that is already present in any of these locations.
• MISSING_KEYS not none → for each listed key with KEY_PROMPTED_<KEY>: no: explain where to get it, ask for the value, and run "$_AK/bin/analyst-kit-setup" set-key <KEY> <value>. If declined, run "$_AK/bin/analyst-kit-setup" skip-key <KEY> (this disables the skills that need it) and continue — never block the skill.
• UPGRADE: UPGRADE_AVAILABLE <old> <new> → say "Analyst Kit skills is available (you have ) — update?". If yes: Read "$_AK/references/upgrade.md" and follow it. If declined: run "$_AK/bin/analyst-kit-update-check" --snooze <new>.
• LEARNINGS entries shown → these are past mistakes/preferences for this user; respect them and do not repeat logged pitfalls.

Then proceed with the skill. At the very end, run the Completion block at the bottom of this file.

Analyst playbook — structure the analysis before touching data

Work through the four steps below in order, before fetching any data. Each one prevents a class of silently-wrong analysis: wrong deliverable, misaligned periods, apples-to-oranges units, or sector conventions ignored.

1. Decide the deliverable first

Every engagement resolves to one of two deliverables. Decide which — it changes what you collect and how you normalize:

• A report or presentation deck → finish with the reporting skill (storyline contract → branded PDF). Collect series wide enough to chart and cite.
• A financial-model update (new actuals into a maintained model — a spreadsheet or model file) → the model-updater skill. It has not shipped yet: until it does, write the normalized series and your assumptions to clearly-named files, and say in your output that the model-update step was done as files.

If the user didn't say which, a comparison/question is a report; "update", "refresh", or "push the new quarter" language is a model update.

2. Alignment checklist — run it for every entity

1. Reporting calendar. Find each entity's fiscal year end before anything else (FMP's fiscal-period data, or the cover of the latest 10-K). Watch the classic offenders: January-ending fiscal years (NVDA, many retailers), the retail 4-5-4 calendar, June/August year ends, Taiwan's monthly revenue cadence.
2. Common period axis. Comparing entities on different calendars: pick ONE axis (usually the more constrained entity's fiscal quarters), re-bin the other's data into it (aggregate months into the target quarters; never interpolate), and state the mapping you used in the deliverable.
3. Units. Different currencies, or an index (search interest, survey, PMI) against dollars → compare year-over-year growth, never raw levels. Same currency and same metric definition → absolute comparison is allowed.
4. Derived numbers come from scripts. YoY/growth/margins via the charting skill's Polars pipeline (python3 -m pipeline.cli yoy … --lag 4 quarterly, --lag 12 monthly) — never computed in your head.

3. Route each series to the right skill

Series	Skill
US/global GAAP fundamentals, prices, transcripts, fiscal periods	financialmodellingprep
Taiwan-listed anything; monthly revenue	finmind
Segment revenue, MD&A, risk factors, anything inside a filing	sec-filings
Non-GAAP KPIs (bookings, DAU, ARR, comps) — never in fundamentals APIs	sec-filings (8-K earnings exhibits, EX-99.x)
Institutional holdings	13f-analysis
Growth math + chart contracts	charting (Polars pipeline + render)
Final document	reporting

4. Apply the sector playbook

Sector conventions decide what "correct" means (a retailer compared on calendar quarters is simply wrong). List this skill's references/ directory and read the playbook matching each entity's sector — for cross-sector comparisons read each one. If no playbook matches, open references/_template.md and use its section headings as your checklist for that sector.

Playbooks are deliberately not enumerated here: new sector files drop into references/ without changing this document.

Completion (run last)

Audit before you deliver. If this run produced a research deliverable carrying quantitative or factual claims — a deep dive, thematic/value-chain map, technical call, company wiki, or financial model — you MUST verify it before presenting it. If a research-auditor subagent is available (the analyst-kit plugin ships one), invoke it via the Task tool, handing it the draft and the data artifacts you used; on a runtime without subagents, run the same checks yourself. Resolve every CRITICAL finding and disclose any UNVERIFIED ones; never deliver on a FAIL verdict without fixing it first. Skip this only for pure data-fetch/utility runs with no analytical claims.

PLAN MODE EXCEPTION — ALWAYS RUN: writes only to ~/.analyst-kit/. Replace OUTCOME with one of DONE | DONE_WITH_CONCERNS | ERROR | ABORT | NEEDS_CONTEXT.

_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
[ -x "$_AK/bin/analyst-kit-log" ] && "$_AK/bin/analyst-kit-log" end --skill analyst-playbook --outcome OUTCOME 2>/dev/null || true

If this session surfaced a durable pattern, pitfall, or user preference that would save 5+ minutes next time (not obvious, not a transient error), also log it:

"$_AK/bin/analyst-kit-learn" add '{"skill":"analyst-playbook","type":"pitfall|pattern|preference","ticker":"<optional>","insight":"<one line>","confidence":7,"ts":"<iso8601 utc>"}'