Changelog - 2025-11-28 (#1)

CLI Utilities for Fund and Company Memos

Overview

Added a focused set of CLI tools to tighten the memo workflow end-to-end:

• Generate exhaustive portfolio listings for emerging manager fund memos.

• Produce scorecards using the Hypernova emerging manager framework.

• Recompile memos from section artifacts with consolidated citations.

• Refocus problematic sections when web research is thin or noisy.

• Improve branded exports so scorecard tables render with even column widths by default.

These CLIs are designed to be composable with the existing artifact + versioning model (output/<Company>-vX.Y.Z) and to respect outline- and mode-specific behavior (especially lpcommit-emerging-manager and mode: "justify").

New CLI Commands

1. describe_all_listed_portfolio_companies.py

Purpose

Enumerate and describe all portfolio companies that appear in a funds internal materials, then write a dedicated 04-portfolio-companies.md section under 2-sections/.

Behavior

• Resolves an artifact directory from either:

  • A company/fund name (e.g., "WatershedVC") via output/versions.json, or

  • An explicit artifact path (e.g., output/WatershedVC-v0.0.1).

• Loads:

  • state.json (for deck-derived deck_analysis and fund metadata).

  • 1-research.json (for prior research context).

• Calls Perplexity Sonar Pro to:

  • Scan deck analysis + research context for any portfolio company mentions.

  • Produce an exhaustive markdown subsection listing each company with:

    • Name

    • One-line description

    • Stage (if known)

    • Thematic fit / rationale

    • Website URL (when available)

• Writes the result to:

  • 2-sections/04-portfolio-companies.md in the artifact directory.

Usage

# Use latest version for WatershedVC
python cli/describe_all_listed_portfolio_companies.py "WatershedVC"

# Use explicit artifact directory
python cli/describe_all_listed_portfolio_companies.py \
  output/WatershedVC-v0.0.1

This is the CLI counterpart to the portfolio_listing_agent design in context-vigilance.

2. generate_scorecard.py

Purpose

Generate an emerging manager scorecard for a fund memo using the Hypernova 12-dimension framework, gated on the proper outline.

Behavior

• Resolves the artifact directory exactly like other CLIs (sanitize_filename + VersionManager).

• Loads state.json and enforces:

  • investment_type == "fund".

  • outline_name == "lpcommit-emerging-manager".

• Invokes scorecard_agent(state) to:

  • Compute the emerging manager scorecard.

  • Persist any scorecard artifacts (e.g., markdown or JSON) referenced in the agent result.

• Prints progress and the location of the generated scorecard file.

Usage

# Use latest version for a fund memo (e.g., Avalanche)
python cli/generate_scorecard.py "Avalanche"

# Target a specific artifact version
python cli/generate_scorecard.py "Avalanche" --version v0.0.5

# Use explicit artifact directory
python cli/generate_scorecard.py output/Avalanche-v0.0.5

3. recompile_memo.py

Purpose

Rebuild 4-final-draft.md from header.md and 2-sections/*.md, then run the citation consolidation utility so footnotes are consistent and deduplicated.

Behavior

• Resolves the artifact directory from:

  • A company name ("Aito"), plus optional --version, or

  • An explicit path like output/Aito-v0.0.2.

• Assembles:

  • Optional header.md.

  • All 2-sections/*.md files, ordered lexicographically by filename (e.g., 01-*, 02-* ...).

• Writes the concatenated content to 4-final-draft.md.

• Invokes cli/utils/consolidate_citations.py (if present) on the final draft to:

  • Consolidate scattered citation blocks.

  • Renumber footnotes sequentially.

Usage

# Recompile latest version for Aito
python cli/recompile_memo.py "Aito"

# Recompile a specific version
python cli/recompile_memo.py "Aito" --version v0.0.2

# Recompile using an explicit artifact directory
python cli/recompile_memo.py output/Aito-v0.0.2

4. refocus_section.py

Purpose

Refocus or repair a specific memo section when web research is thin, noisy, or conflicting, especially for mode: "justify" fund memos.

Behavior

• Mirrors the interface and artifact handling of cli/improve_section.py but with a stricter contract:

  • Web research is optional and never allowed to block completion.

  • When web content is sparse or conflicting, the agent:

    • Emits a short, easy-to-spot line near the top, e.g.:

      • "Web research returned limited fund-specific information; falling back to narrative based on internal materials."

    • Then produces the best possible narrative based on internal context only:

      • Deck-derived analysis in state.json.

      • Existing memo sections in 2-sections/.

      • Company metadata in data/<Fund>.json.

• Loads artifacts from the resolved output directory:

  • state.json

  • 1-research.json

  • 2-sections/*.md

  • Optional 3-validation.json

• Writes the updated section back into 2-sections/, then reassembles 4-final-draft.md.

Usage

# Refocus Recommendation for latest WatershedVC memo
python cli/refocus_section.py "WatershedVC" "Recommendation"

# Refocus Risks & Mitigations for a specific version directory
python cli/refocus_section.py output/WatershedVC-v0.0.1 "Risks & Mitigations"

This CLI operationalizes the behavior described in context-vigilance/issue-resolution/Getting-AI-to-Refocus-when-Web-Research-is-empty.md.

Updated CLI Behavior

export_branded.py: Normalize Scorecard Table Columns

Change

• Added a post-processing step to normalize <colgroup> widths in exported HTML so scorecard tables render with even column widths by default.

• The new helper:

  • Scans each <colgroup> in the generated HTML.

  • Counts <col> elements and assigns each a style="width: 100/n%" inline style.

  • Strips any existing style="width: ..." fragments before reapplying.

• This runs after Pandoc conversion and before citation/footnote fixups.

Why

• Without this, wide scorecard tables (especially the emerging manager dimensions) could have visually unbalanced columns depending on Pandoc output and CSS.

• Normalizing widths provides deterministic, readable scorecard layouts across brands and export modes.

Files Changed

New Files (6)

Modified Files (1)

Why This Matters

Tighter CLI Surface for the Memo Workflow

These CLIs turn previously semi-manual steps into repeatable commands that fit the artifact/versioning model:

1. Portfolio listings become first-class artifacts.

   • Fund memos can now reliably include an exhaustive Current Portfolio subsection derived from internal materials rather than ad-hoc mentions.

2. Scorecards move from concept to runnable tool.

   • The Hypernova emerging manager framework is now wired into a CLI that respects investment_type and outline_name.

3. Recompilation and citations are one step.

   • Its now easy to iterate on sections and recompile the final draft without manually stitching files or fixing footnotes.

4. Justify-mode behavior is enforced in code, not just docs.

   • The refocus_section CLI encodes the desired fallback behavior when web research is thin, preventing half good, half cliff memos.

5. Branded exports produce cleaner tables.

   • Scorecard-heavy memos now have more legible, consistent tables across brands and output versions.

Usage Summary (CLI Entrypoints)

# Portfolio listing for a fund memo
python cli/describe_all_listed_portfolio_companies.py "WatershedVC"

# Emerging manager scorecard for a fund memo
python cli/generate_scorecard.py "Avalanche" --version v0.0.5

# Recompile memo and consolidate citations
python cli/recompile_memo.py "Aito" --version v0.0.2

# Refocus a problematic section in JUSTIFY mode
python cli/refocus_section.py "WatershedVC" "Recommendation"

# Export branded HTML/PDF (with normalized scorecard tables)
python cli/export_branded.py output/WatershedVC-v0.0.1/4-final-draft.md \
  --brand hypernova --mode dark --pdf

Next Steps

• Wire describe_all_listed_portfolio_companies.py into the automated enhancement workflow for lpcommit-emerging-manager memos.

• Extend generate_scorecard.py to optionally insert a scorecard table directly into the memo body.

• Add integration tests that run the new CLIs against a sample fund memo artifact directory.

• Document these CLIs in README.md and/or dedicated CLI docs.

Contributors

Implementation by Claude Code (Cascade) with user guidance.