Analysis workflow

Choose the Codex skill for the stage

These skills are the workflow entry points. Use them from the Investment repository root; Codex will inspect the ticker workspace, preserve source files, and resume existing state where possible.

Quick start

1. Open the Investment workspace. Work from the repository root that contains app/, stocks/, and .agents/skills/.
2. Create the ticker workspace. Use the supported command; it copies the reviewed scaffold, initializes source state and a pending neutral report theme, then validates the folder contract:

   python3 -B -m app.stock_workspace create <TICKER> \
     --company "Company Name" --exchange "NASDAQ"

3. Add source documents. Put them anywhere under stocks/<TICKER>/sources/. Keep the raw files unchanged.
4. Scan and ask Codex to run it.

   python3 -B -m app.source_intake <TICKER> scan
   
   Use $analyze-equity to analyze <TICKER>

   For a fresh run, provide portfolio context when relevant. Without it, the manifest records clearly labeled Watching defaults.

5. Let the workflow pass its gates. Codex reviews required visuals, locks canonical facts and core calculations, prepares v4 retrieval, and records cited support and counter-evidence for each step.
6. Confirm the analysis gate. The Phase 0 workflow is complete only when validation prints VALID. Then choose the next artifact:

   Use $equity-report for <TICKER>
   Use $kpi-handoff for <TICKER>

What you need

Supported files

• Extracted: PDF, Markdown, plain text, HTML, and HTM.
• Cataloged for visual review: PNG, JPG, and JPEG.
• Unreadable files: recorded as source errors without aborting other usable sources.
• Discovery: recursive; nested folders are allowed and evidence remains isolated by ticker.

Folder structure

Investment/
├── .agents/skills/
│   ├── analyze-equity/             # Phase 0 analysis and validation
│   ├── equity-report/              # private HTML report
│   └── kpi-handoff/                # public-safe KPI projection
├── app/
│   ├── analysis_prompts/           # 14 numbered prompts
│   ├── phase0_analysis.py          # prepare, retrieve, facts, calculate, validate
│   ├── equity_report.py            # prepare, status, render, validate
│   ├── kpi_handoff.py              # build and promote KPI artifacts
│   └── source_intake.py            # initialize, scan, and mark source tracking
├── requirements.txt                # pypdf and Markdown
└── stocks/
    └── <TICKER>/
        ├── README.md
        ├── sources/
        │   ├── quarterly/
        │   ├── events/
        │   ├── news/
        │   └── analyst-research/
        ├── trackers/                # durable thesis and KPI pointers
        └── outputs/
            └── phase0/
                └── <run-id>/

The source subfolders are a useful taxonomy, not a restriction. The helper inventories every supported file beneath sources/ and never moves, renames, converts, or overwrites it.

Recommended source packet

More evidence improves coverage, but the packet should stay current, relevant, and legally usable.

Phase 0 lifecycle

Codex normally runs these commands for you. They are documented here for inspection, recovery, and manual verification.

Run them from the Investment repository root. For a different checkout location, add --root /path/to/Investment before the ticker.

1. Scan source intake

python3 -B -m app.source_intake <TICKER> scan

Reports new or modified files without marking them. After a completed validated run, source intake can be marked through validate --mark-sources.

2. Prepare or resume

python3 -B -m app.phase0_analysis <TICKER> prepare

Builds the evidence catalog and chunks, then resumes the newest incomplete run. Use --new-run only when a fresh fingerprinted run is needed.

python3 -B -m app.phase0_analysis <TICKER> prepare --new-run

Optional portfolio context

python3 -B -m app.phase0_analysis <TICKER> prepare \
  --position-status Holding \
  --shares 125 \
  --average-cost 42.50 \
  --cost-currency USD \
  --current-allocation 3 \
  --target-allocation 5

Allowed position states are Watching and Holding. A holding requires shares, average cost, three-letter cost currency, current allocation, and target allocation. Without supplied context, the manifest records clearly labeled Watching defaults.

3. Review required visuals

python3 -B -m app.phase0_analysis <TICKER> review
python3 -B -m app.phase0_analysis <TICKER> review --mark <VISUAL-ID>

Inspect every listed preview before writing analysis. Mark only the visual IDs actually reviewed; do not begin the 14 steps while the run reports review_required.

4. Lock facts and core calculations

python3 -B -m app.phase0_analysis <TICKER> facts prepare
python3 -B -m app.phase0_analysis <TICKER> facts build
python3 -B -m app.phase0_analysis <TICKER> facts status
python3 -B -m app.phase0_analysis <TICKER> facts validate --lock
python3 -B -m app.phase0_analysis <TICKER> calculate core

Populate the fact candidates with source-backed assertions, preserve conflicts explicitly, and keep reported facts, guidance, estimates, market observations, and analyst assumptions distinct. Do not write Step 1 until facts and core calculations are locked.

5. Prepare deterministic v4 retrieval

python3 -B -m app.phase0_analysis <TICKER> retrieve prepare
python3 -B -m app.phase0_analysis <TICKER> retrieve plan --step <N>
python3 -B -m app.phase0_analysis <TICKER> retrieve search "<SUPPORT QUERY>" --step <N> --kind support --explain
python3 -B -m app.phase0_analysis <TICKER> retrieve search "<COUNTER QUERY>" --step <N> --kind counter --explain
python3 -B -m app.phase0_analysis <TICKER> retrieve validate --step <N>

For each step, satisfy the plan or record a gap, conflict, or review requirement. Register only material claims in the evidence sidecar and retain the counter-search trace even when it finds nothing.

6. Complete, calculate, and synchronize

python3 -B -m app.phase0_analysis <TICKER> status
python3 -B -m app.phase0_analysis <TICKER> calculate valuation
python3 -B -m app.phase0_analysis <TICKER> calculate decision

Write each numbered output from its prompt and cited evidence, starting at next_step. After Step 7, lock valuation assumptions and results; after Step 11, lock decision arithmetic before Step 12.

7. Validate the complete run

python3 -B -m app.phase0_analysis <TICKER> validate --mark-sources

Use --run-id <RUN_ID> to validate a non-default run. Completion requires VALID; accepted Markdown, evidence sidecars, retrieval traces, facts, and calculations are immutable.

The 14-step prompt sequence

The prompts run sequentially. They are not independent parallel reports: later judgments consume locked facts, calculations, retrieval evidence, and handoffs from earlier steps. The v4 run also accepts each Markdown output together with its step evidence sidecar and retrieval trace.

Required handoffs

• Facts and core calculations → Step 1 onward: use locked values and preserve their fact or result IDs alongside the original source citations.
• Step 1 → Steps 5 and 7: use the detected business phase.
• Step 7 → Steps 10 and 11: use one consistent valuation method, assumptions, and scenario inputs.
• Steps 10 and 11 → Step 12: explicitly synthesize market-implied expectations and intrinsic value.
• Portfolio manifest → Steps 12 and 13: use supplied position data or clearly labeled defaults.
• All prior steps → later steps: use concise cited handoffs instead of duplicating whole outputs; validate each v4 sidecar before status can accept it.

Private quality-gated HTML report

$equity-report is separate from $analyze-equity. It accepts a completed analysis-contract-v2, v3, or v4 run, preserves all 14 accepted outputs, and creates a cited synthesis plus a deterministic standalone HTML report. It never runs the analysis steps or publishes the private artifact for you.

Command lifecycle

python3 -B -m app.equity_report <TICKER> prepare [--run-id <RUN>]
python3 -B -m app.equity_report <TICKER> status [--run-id <RUN>]
python3 -B -m app.equity_report <TICKER> render [--run-id <RUN>]
python3 -B -m app.equity_report <TICKER> validate [--run-id <RUN>]

What the report contains

• A decision-first opening with dated market data, evidence confidence, underwriting status, and portfolio context.
• Thesis, variant perception, business quality, operating drivers, valuation scenarios, risks, catalysts, falsifiers, and monitoring triggers.
• A behavioral circuit breaker covering confirmation, overconfidence, herding, recency, sunk-cost or house-money effects, concentration, and cooling-off questions.
• An aggregate evidence-quality summary, explicit contradictions, unresolved gaps, linked source register, and all 14 accepted outputs in a navigable appendix.

Public-safe KPI handoff

$kpi-handoff connects a completed v4 analysis to a deterministic KPI dashboard without scraping a report or exposing portfolio context. It reads locked facts, calculation results, reviewed evidence, and approved selections.

Command lifecycle

python3 -B -m app.kpi_handoff <TICKER> prepare [--run-id <RUN>]
python3 -B -m app.kpi_handoff <TICKER> build [--run-id <RUN>]
python3 -B -m app.kpi_handoff <TICKER> preview [--run-id <RUN>]
python3 -B -m app.kpi_handoff <TICKER> validate [--run-id <RUN>]
python3 -B -m app.kpi_handoff <TICKER> promote [--run-id <RUN>]

1. Prepare: select the newest completed v4 run unless a run ID is explicitly named.
2. Curate: add stable KPI definitions, typed observations, thresholds, catalysts, risks, and monitoring triggers with lineage.
3. Build and preview: compile the internal handoff and the redacted public projection; preview reads only the public projection.
4. Validate: confirm hashes, source lineage, compatible periods and units, reviewed visuals, and absence of private fields.
5. Promote: explicitly lock the validated run as trackers/kpi_current.json. Promotion does not publish or modify the public Reports site by itself.

Public report and site bundle

The public full report is a separate artifact, not a copy of the personalized report. It requires a completed v4 analysis, a validated KPI handoff, and an official-source-verified company theme.

python3 -B -m app.public_equity_report <TICKER> prepare [--run-id <RUN>]
python3 -B -m app.public_equity_report <TICKER> status [--run-id <RUN>]
python3 -B -m app.public_equity_report <TICKER> render [--run-id <RUN>]
python3 -B -m app.public_equity_report <TICKER> validate [--run-id <RUN>]

python3 -B -m app.site_publication <TICKER> prepare [--run-id <RUN>]
python3 -B -m app.site_publication <TICKER> validate [--run-id <RUN>]

The bundle fingerprints the public report, KPI dashboard, verified theme, card metadata, and exact website destinations. Applying it requires the explicit --confirm-publication flag; it updates the local website checkout and rebuilds data/library.json, but never commits or pushes.

Outputs and resumable state

stocks/<TICKER>/outputs/phase0/<run-id>/
├── Step_01_Output.md
├── Step_02_Output.md
├── ...
├── Step_14_Output.md
├── step_evidence/                  # v4 evidence sidecars
├── retrieval_traces/               # v4 retrieval traces
├── evidence_catalog.json
├── evidence_chunks.jsonl
├── evidence_blocks.jsonl
├── evidence_tables.jsonl
├── evidence_visuals/
├── facts_ledger.json                # after facts validate --lock
├── calculation_results/             # after calculate stages
├── run_manifest.json
├── Report_Synthesis.md             # after $equity-report
├── <TICKER>_Full_Report.html       # private personalized report
├── report_manifest.json             # independent report fingerprints
├── kpi_handoff_public.json          # after $kpi-handoff build
├── KPI_Dashboard_Preview.html       # after $kpi-handoff preview
├── Public_Report_Synthesis.md       # curated public-only synthesis
├── <TICKER>_Public_Report.html     # separate public report
├── public_report_manifest.json
└── publication_bundle.json          # exact hashes and site destinations

• run_manifest.json records the contract, status, detected phase, assumptions, prompt and source hashes, citations, web sources, timestamps, and failures.
• evidence_catalog.json inventories the usable sources, images requiring inspection, and isolated source errors.
• evidence_blocks.jsonl, evidence_tables.jsonl, and evidence_visuals/ retain structured context for reliable review.
• For v4, each accepted step hashes its Markdown output, evidence sidecar, and retrieval trace together.
• The newest incomplete run resumes by default. A completed run or explicit --new-run creates a new timestamped run.
• report_manifest.json fingerprints the accepted analysis, synthesis, styles, portfolio context, and rendered HTML without modifying run_manifest.json.
• KPI handoff artifacts are fingerprinted separately; promotion writes only the validated run ID and hashes to trackers/kpi_current.json.

Evidence and citation rules

• Prefer local evidence and read the original document when a search result needs surrounding context.
• Supplement only when required information is absent locally, using primary sources such as the SEC, company investor relations, official exchanges, or regulators.
• State an as-of date for web evidence.
• Mark unsupported, unavailable, or stale facts as evidence gaps rather than estimating them.
• Use the citation strings returned by evidence search. Never invent page numbers or chunk IDs.
• For v4, register every material local or web citation in the step evidence sidecar; IDs supplement citations and never replace them.
• Keep reported actuals, guidance, consensus estimates, market observations, and analyst assumptions distinct. Preserve conflicts instead of averaging them.

Local PDF:  [[source:quarterly/example.pdf#page=12]]
Local text: [[source:events/example.md#chunk=0123456789abcdef]]
Primary web: [Company filing](https://example.com/filing), published YYYY-MM-DD

Every material factual paragraph or table row should be traceable, and each step must contain at least one machine-checkable citation. Quantitative claims must also resolve to a locked fact or calculation result when the contract requires it.

Troubleshooting

Publication safety

• Keep files beneath sources/ unchanged and outside the public site.
• Publish only permitted derived analysis and citations—never licensed documents, credentials, private paths, portfolio details, raw evidence, or a personalized full report.
• Public KPI projections may retain only allowlisted values backed by dated primary HTTPS sources; withheld items must remain explicit gaps.
• Public reports use Public_Report_Synthesis.md and the public renderer; never copy the private <TICKER>_Full_Report.html into the website.
• Verify trackers/report_theme.json against an official HTTPS source before creating a publication bundle.
• Review generated output for sensitive information before publication and run browser checks at desktop and 390px mobile widths.