surface

Follow CLAUDE.md Writing Standards strictly. No hedge words, lead with insights/numbers, tables over prose, every sentence must earn its place.

Perform deep insight discovery across the vault. This is the highest-value operation — finding connections and opportunities the user hasn't seen yet.

Execution context — subagent delegation (2026-07-08, MANDATORY)

Delegate the ENTIRE run (Step 0 pre-flight through Phase 4 output) to ONE Agent subagent (subagent_type: general-purpose, run_in_background: false). Pass this skill's full instructions plus the resolved scope in the agent prompt. The subagent performs all reads, analysis, lock acquire/release, and writes (Research note + _hot.md + _followups.md), and must END its final message with the complete user-facing report. The main thread renders that returned report verbatim in chat — never re-summarize it, never discard sections.

Mental Models reading gate MUST cross the delegation boundary (MANDATORY — CLAUDE.md; _shared/mental-models-section.md). The subagent does NOT inherit CLAUDE.md, so the agent prompt MUST embed this gate verbatim: "Before ranking any opportunity, read Mental Models/Generalist - Overview.md (always) + the matching Mental Models/Industry - X.md for sectors in scope + any relevant Mental Models/Lens - X.md. Apply the READING PROTOCOL — models are lenses/questions held as hypotheses, never verdicts; run the base-rate/outside view adversarially; treat agreement across models as a trigger to disconfirm, not to commit." An agent prompt omitting this is a spec violation — surface's whole job (finding non-consensus inflections) is the READING PROTOCOL applied at portfolio scale.

Recursion guard — the agent prompt MUST also embed verbatim: "You are the EXECUTOR of this skill run, not a coordinator: do NOT re-delegate any part of this work to further Agent calls — the 'Execution context — subagent delegation' section of the instructions you were passed applies to the main thread only and is already satisfied by your existence. Perform all reads, analysis, and writes yourself, and end your final message with the complete user-facing report." Without this line the passed instructions include the delegation mandate itself — an invitation to recurse.

Scope Resolution ownership: the MAIN THREAD resolves scope (Scope Resolution section below) BEFORE delegating and passes the resolved scope in the prompt; the subagent starts at Step 0 pre-flight with scope already fixed (Step 0's lock scope depends on it, so resolution cannot live inside the subagent).

Why delegation, not frontmatter fork: context: fork was reverted 2026-06-07 (forked output returned as unrendered stdout — blank panel). Delegation keeps the read set (~150-200K words default with section-targeted thesis + sector reads; ~960K words all mode — full-read only) out of main context while the main thread does the rendering. Main-context cost: the returned report only.

Step 0: Pre-flight (MANDATORY — runs before Scope Resolution)

0.1: Acquire vault lock

• Unscoped /surface (full vault): acquire a vault-wide scope lock per .claude/skills/_shared/preflight.md Procedure 1. Timeout budget: 10 minutes.
• Scoped /surface TICKER: acquire a ticker:TICKER scope lock. Timeout budget: 5 minutes.
• Scoped /surface [sector]: acquire a vault-wide scope lock (the sector set spans multiple tickers; concurrent ticker-scoped writers would race on sector note edits). Timeout budget: 10 minutes.

Capture the token emitted at Step 0.1, verify ownership (Procedure 1.5) at every subsequent Bash block, release in the final reporting Bash block via rm -f "$LOCK_FILE".

0.2: Rename-marker pre-flight (ticker-scoped mode only)

For /surface TICKER, run .claude/skills/_shared/preflight.md Procedure 2. If .rename_incomplete.TICKER exists, hard-block per contract 2.3. For unscoped and sector-scoped modes, check .rename_incomplete.* at vault root; if any marker exists, emit a warning but DO NOT abort (surface is read-mostly for these modes — it writes a research note but does not edit thesis wikilinks). Warning text: ⚠️ In-flight rename repair(s) detected: [list markers]. Surface scan will proceed but its research note's wikilinks to the affected ticker(s) use current filenames. Complete rename repair before running downstream /sync.

Scope Resolution

Parse $ARGUMENTS to determine scope:

• all (literal keyword): Full vault, full-read mode (comprehensive, legacy pre-2026-04-21 behavior). Reads every thesis, sector, and macro note in full. Use when doing a once-off deep review and willing to pay the larger context cost for maximum signal.
• Ticker (e.g., NVDA): Read _graph.md and resolve the ticker's adjacency set — its thesis, sector note(s), macro note(s), cross-thesis references, and all linked research. Also include theses that share a sector (one ring outward) for competitive context. Adjacency-miss branch (thesis newer than the graph): if the ticker has no adjacency entry in _graph.md BUT Theses/TICKER - *.md exists on disk (e.g. /surface CBRS when CBRS was created after the last /graph run), do NOT treat it as unknown — warn ℹ️ [TICKER] not yet in _graph.md (created since last /graph run) — resolving from disk; run /graph last for full adjacency. then resolve the scope set from the thesis file directly: its sector: frontmatter (→ sector note via the resolution procedure below) + its ## Related Research wikilinks + Log-mentioned macro notes. This is the mirror of the existing archived-thesis validation (graph lists a file that's gone); here disk has a file the graph lacks.
• Sector (e.g., semiconductors): Resolve the argument to a sector note via _shared/sector-resolution.md (the canonical procedure — case/whitespace/punctuation tolerant), NOT a raw case-sensitive _graph.md key lookup. Then use the _graph.md Sector → Theses reverse index (keyed on the RESOLVED sector-note name) to gather all theses in that sector, plus the sector note, related macro notes, and their linked research.
• No arguments / empty: Full vault, section-targeted mode (default). Reads bounded per-thesis sections only — fast, lean, suitable for weekly/monthly cadence.

Argument disambiguation: all is a reserved keyword (matches /sync all precedent). Never a ticker — no archived or live thesis with that filename pattern. Never a sector — no sector note named all. all is accepted in any case (all, ALL, All).

Sector matching is case-INSENSITIVE via _shared/sector-resolution.md. The prior "case-sensitive for ticker/sector match" rule made the skill's OWN documented example /surface semiconductors (and User Guide's) resolve to zero matches, because the graph key is Semiconductors & AI Infrastructure, not semiconductors. Route every sector argument through the resolution procedure; the ticker match stays exact (tickers are canonical uppercase/numeric filenames).

No-match behavior (both scoped modes). If the argument resolves to neither a ticker (no Theses/ARG - *.md on disk AND no graph adjacency) NOR a sector (sector-resolution.md returns match_confidence: none), STOP with: ⚠️ /surface [ARG] — "[ARG]" matched no thesis (Theses/[ARG] - *.md) and no sector note (via sector-resolution). Check the ticker/sector name, or run /surface (no args) for a vault-wide scan. No research note written. Do NOT silently fall back to a vault-wide scan (that would write a note the user didn't scope for).

If a non-all scope is requested but _graph.md does not exist, warn: ⚠️ Graph missing — cannot scope. Run /graph first, or run /surface (default, section-targeted) or /surface all (full-read) without arguments. Then stop. (Exception: the adjacency-miss branch above still resolves a ticker from disk when the graph merely lacks that one new thesis — a missing graph FILE is different from a graph that is present but stale for one ticker.)

Scope-set existence validation (ticker-scoped and sector-scoped modes only)

After resolving the scope set from _graph.md and before reading any thesis files, validate that every resolved thesis's file still exists on disk. _graph.md's reverse indexes and adjacency entries reflect the last /graph run's filesystem state; closures via /status active→closed or /prune between that run and now mv files to _Archive/ without touching _graph.md. Scoped /surface would otherwise resolve archived theses into the scope set and fail when reading them — producing silently incomplete analysis.

Validation rule:

1. Collect resolved_theses: [Theses/TICKER - Name.md, ...] from Scope Resolution output.

2. For each path, test existence:

   for path in resolved_theses:
       [ -f "$path" ] || record_as_missing "$path"
   

3. If missing: [ ] is empty → proceed to Phase 1 normally.

4. If missing: [ ] is non-empty:

   Sector-scoped mode: stop the skill immediately. Do NOT proceed with a partial scope — scoped portfolio-level output (research velocity ranking, attention allocation, decay alerts) depends on complete coverage; a partial scope silently under-reports these metrics without flagging the gap. Report:

   ⚠️ Scope resolution via _graph.md found [N] thesis(es) still listed in the Sector → Theses reverse index but no longer present in Theses/:
     - [missing path 1]
     - [missing path 2]
     ...
   
   _graph.md is stale relative to filesystem state — likely a /status active→closed or /prune closure since the last /graph run.
   
   Resolution: run /graph last (consumes .graph_invalidations, rebuilds reverse indexes from current filesystem state, excludes archived theses). Then re-run /surface [sector].
   
   No surface-scan research note was written for this run.
   

   Ticker-scoped mode: if the scoped ticker itself is in missing:, report:

   ⚠️ /surface [TICKER] — thesis file not found at Theses/[TICKER] - *.md. Likely archived since the last /graph run.
   
   Options:
     (a) Run /rollback [TICKER] to reopen the archived thesis (then /sync TICKER → /graph last → re-run /surface [TICKER]).
     (b) Run /surface without arguments for a vault-wide scan that will correctly exclude the archived ticker.
     (c) Run /graph last to rebuild indexes from current filesystem state, then re-run /surface [TICKER] — but expect the same error if the thesis is archived.
   
   No surface-scan research note was written for this run.
   

   Stop the skill in either ticker-scoped sub-case.

Why stop rather than best-effort continue

Design rationale in .claude/skills/surface/RATIONALE.md §1.

Why not auto-run /graph last

Design rationale in .claude/skills/surface/RATIONALE.md §2.

Phase 1: Portfolio Scan (mode-dependent read strategy)

Read strategy branches by scope. The two full-vault modes trade completeness against main-session context budget:

Mode	Thesis reads	Sector reads	Expected read budget	Use when
/surface (default)	Section-targeted (frontmatter + 4 sections + last 5 Log)	Section-targeted (4 sections + last 5 Log, all ~50)	~150-200K words	Weekly / monthly cadence; part of a maintenance chain
/surface all	Full read (entire file per thesis)	Full read (all ~50)	~960K words — exceeds a single subagent context; run only on explicit all with the user accepting the cost	Once-off deep review; maximum signal
/surface TICKER	Full read of scope set	Full read of the ticker's sector note(s) only	~20-40K words	Ticker-focused insight discovery
/surface [sector]	Full read (≤6 theses) or section-targeted (>6 theses)	Full read of the one resolved sector note	~20-80K words	Sector-level review

Unscoped default mode — section-targeted reads

1. For each thesis file in Theses/*.md (every file — draft, active, monitoring; not just active):
   • Read only: frontmatter + ## Summary + ## Key Non-consensus Insights + ## Risks + ## Catalysts + last 5 Log entries
   • Skip: Business Model & Product Description, Industry Context, Key Metrics, Bull Case, Bear Case, Outstanding Questions, Related Research, older Log entries
   • Target: ~800-1,500 words per thesis instead of ~4,000-6,000 — reduces total thesis read from ~175K words to ~35-50K words
   • Extract via the shared helper (2026-07-08 — replaces the prior brittle inline awk range-patterns, which silently mis-extracted on any heading drift that /lint #14 flags; the script is heading-case/whitespace/prefix tolerant and reports missing sections):

python3 .claude/skills/_shared/extract_sections.py Theses/*.md \
  --sections "Summary,Key Non-consensus Insights,Risks,Catalysts" --log-tail 5

One call handles every thesis; output is grouped per file (===== FILE: ... =====) with a --- missing sections: ... --- line whenever a thesis lacks a requested heading (surface that as a template-drift signal, don't silently drop it). Exit 3 = a file was unreadable (self-validation); investigate rather than proceeding on partial output.

2. Sector Notes are section-targeted too, NOT read in full. There are ~50 sector notes ≈ 445K words (the old "~13 files, read in full" count was stale by ~4× and, read in full, alone exceeds the delegated subagent's entire context — the run would silently truncate on exactly the sections the edge lives in). Extract only the highest-signal sector sections via the same helper:

python3 .claude/skills/_shared/extract_sections.py Sectors/*.md \
  --sections "Key industry questions,Competitive dynamics,Investor heuristics,Mental Models" --log-tail 5

This cuts ~445K → ~110-130K words while keeping the non-consensus surface (Investor heuristics = what's priced in / where consensus is wrong; Competitive dynamics = pricing-power trajectory). Full-read a sector note ONLY if a specific opportunity thread requires its Product-level or Industry-history detail — targeted, not blanket.

3. Issue steps 3-4 as a single parallel tool-call batch (after the Step 1 + Step 2 extractor blocks land): all Macro Note Reads (~8-9, full) + all heavily-cited research note Reads (~10-20) in ONE message. Do NOT serialize.
4. Read all Macro Notes in full (bounded set, ~8-9 files). Scenario frameworks require complete context.
5. For heavily cited research notes (appearing in ≥3 theses' Related Research via _graph.md orphan+adjacency lookup): read in full. All other research notes: trust the thesis Log citations as summaries.

Expected read budget: ~150-200K words total (thesis-targeted ~35-50K + sector-targeted ~110-130K + macro ~15K + cited research). The prior "~50-80K" line assumed the stale 13-sector count; at 50 sectors even the targeted budget is larger, but it stays within a delegated subagent's context — a full-read of all 50 sectors (~445K words + ~127K thesis + macro > 600K words) would not. The all mode's true cost is ~960K words and MUST run full-read only when the user explicitly accepts it.

/surface all mode — full-read comprehensive scan

Use when the user wants maximum analytical depth for a once-off deep review. Reads every thesis file in full — accepts the larger main-session context cost for richer cross-thesis connection detection (particularly valuable for Business Model and Industry Context cross-referencing that section-targeted mode misses).

Issue ALL reads in steps 1-3 as a single parallel tool-call batch — one message with every thesis Read (~76), every Sector Read (~50), and every Macro Read (~8-9) firing in parallel. Do NOT serialize. Step 4's heavily-cited research reads join the same parallel batch when _graph.md adjacency is already loaded; otherwise they land in a second parallel batch after the Step 1-3 batch returns.

1. Read every Theses/*.md in full (all 15 thesis sections). No extraction.
2. Read all Sector Notes in full (~50).
3. Read all Macro Notes in full (~8-9).
4. For heavily cited research notes (≥3 theses in _graph.md adjacency): read in full — include in the parallel batch with steps 1-3 (one round-trip). For others: read on-demand when Phase 2 analysis surfaces a specific question about them.

Expected read budget: ~960K words total (76 theses ~127K + 50 sectors ~445K + macro ~15K + cited research + growth since pre-R2) — this exceeds a single delegated subagent's context window. Run all mode only when the user explicitly requests it AND accepts that the subagent may need to chunk the read across multiple passes or that coverage of the lowest-signal sections may be partial; log any section dropped. Default section-targeted /surface (~150-200K subagent words) remains the lean routine-cadence choice and the safe default; reserve all for deliberate deep reviews where the user has accepted the cost.

Output differentiation: /surface all research notes carry source_type: synthesis with scope: all in a scope: frontmatter field, so downstream review can distinguish deep-scan outputs from routine /surface scans. Filename: Research/YYYY-MM-DD - Insight Surface Scan (all).md.

When to prefer /surface over /surface all: unless you're explicitly doing a quarterly/annual portfolio deep-review, default mode is strictly better — same insight signal at 25% the read cost. /surface all is the escape hatch for cases where section-targeting empirically misses a cross-section pattern.

Scoped mode — reads bounded by scope resolution

Ticker-scoped /surface TICKER: read the resolved ticker + adjacencies (thesis, sector, macros, cross-thesis, linked research, sector peers). Set is small (1 focal thesis + 2-6 peers); section-targeting not needed — read all files in full for full competitive context.

Sector-scoped /surface [sector]: read the sector note + all theses in that sector + linked macros + their research. Typical set is 3-8 theses; apply section-targeting (as in default mode above) only if the sector has >6 theses.

Skip vault-wide checks that require full portfolio coverage (Attention Allocation ranking, Research Velocity ranking across all theses — these need the full set to be meaningful).

Phase 2: Connection Analysis

Portfolio Blind Spots

• Identify sectors or sub-sectors the vault's theses imply are important but have NO coverage. (e.g., if you hold BESI + LITE + NVDA, you're implicitly betting on advanced packaging — do you cover the substrate suppliers? The test equipment vendors? The materials companies?)
• Flag value chain nodes that appear in multiple theses' Risk sections but have no dedicated research — these are unmonitored dependencies
• Check for "implied but unwritten" theses — tickers mentioned in 3+ research notes that still have no Thesis note. These are ideas the vault has been circling without committing to
• Identify adjacent companies that vault research strongly implies should be covered based on competitive dynamics in Sector Notes

Supply Chain Mapping

• Which thesis companies are suppliers, customers, or competitors of each other?
• Are there hidden portfolio correlations? (e.g., multiple bets on the same underlying trend)
• Would a single event break multiple theses simultaneously?

Macro Exposure Audit

• Map each thesis against current macro scenarios (Iran conflict, AI bubble risk, rate expectations)
• Flag theses with unacknowledged macro sensitivity
• Identify natural hedges within the portfolio

Catalyst Calendar

• What upcoming events could move multiple positions?
• Are there clustered earnings dates that create portfolio risk?
• Any regulatory, geopolitical, or technology milestones approaching?

Contrarian Signal Detection — delegated to /retro (2026-07-08 de-overlap).

• The vault-vs-market gap (where vault conviction diverges from market pricing) is /retro's flagship: it computes the narrative-price delta rigorously against actual price moves + newsflow polarity, not an ad-hoc web guess. /surface no longer re-derives it (doing so duplicated ~per-ticker web queries with no shared query plan and produced a weaker, price-blind version of the same signal).
• /surface's job here is only to flag which positions look most worth a market-reaction check, then defer: → Run /retro [window] (or /retro [window] TICKER for a single name) to quantify the gap and rank trade ideas. Do not issue price/consensus web searches from /surface.

Research Freshness Audit (forward attention only — no market overlay)

• From vault data alone: which theses have the oldest last-Research/-note date? Rank them. This is a what-to-research-next signal (surface's forward domain).
• Do NOT web-search for "recent developments" here — that market-overlay work belongs to /retro (backward) and /catalyst (forward events). Surface flags the staleness; retro/catalyst supply the external delta.

Thesis Velocity & Attention Allocation

• Research velocity ranking: Which theses received the most research activity recently (new Research/ notes, Log entries, edits)? Which received zero? Rank all active theses by volume of recent activity.
• Attention vs conviction alignment: Compare where research time was spent against conviction levels. Flag any mismatch — disproportionate time on low-conviction ideas while high-conviction theses go unattended is a resource allocation error.
• Decay alert: List any active thesis that hasn't been touched (no Log entry, no new linked research) in 30+ days. These are candidates for /deepen or /prune.

Phase 2.5: Story-log drift mining (unscoped and all modes only — 2026-07-20)

The n8n Workflow 3 news sweep writes one machine-readable story log per run to .data/news_stories/*.json (schema: {date, stats, stories: [{title, cluster, score, sum, members}]}). This corpus records what actually scored high against current coverage — the empirical check on whether the watcher registry is drifting behind reality.

1. Read (skip silently if the folder is absent or empty — the sweep may not be live): ls .data/news_stories/*.json → parse the last track_window_d days of files (registry Tuning row, default 30). Budget guard: read at most 60 files.
2. Aggregate stories with score ≥ track_min_score (registry Tuning row, default 8). Group by recurring subject (same company/technology/theme appearing across ≥3 distinct days). Sentiment trajectory: for any ticker/theme with ≥3 days of coverage, also read each story's sig/markers (the 𝕏 bullish/bearish/quiet and catalyst-proximity tags Assemble stamped) across the window — a directional shift (e.g. 𝕏 flips bearish→bullish, or scores trend up) is a tracked sentiment change worth surfacing alongside the drift signals. The logs are the substrate; this read is the 30-day sentiment view the user asked for.
3. Compare against the registry: read _watchers.md § News & Thematic. Two drift signals:
   • Missing watcher: a recurring high-score subject with NO matching registry row → the sweep is catching it only incidentally (via outlet feeds or ticker queries); a dedicated thematic row with a proper thesis anchor would track it deliberately. Propose the row (id, query, thesis link, expires) in the report.
   • Dead watcher: an active registry row whose query subject produced ZERO stories (any score) across the window → the theme has gone quiet or the query is mistuned. Propose paused or a query rewrite.
4. Output: add a ### Registry drift section to the Phase 4 report listing proposed row additions/retirements — proposals only, the user edits _watchers.md (or asks Claude to). Registry drift findings do NOT go to _followups.md (they are config hygiene, not research opportunities) — EXCEPT when a missing-watcher subject also generates a Phase 3 opportunity, in which case the opportunity entry carries it.

This phase feeds Phase 3: a recurring high-score subject with no thesis anchor anywhere in the vault is itself a candidate opportunity (new-thesis or macro-note gap).

Phase 2.7: Coverage blind-spot screen (Quartr GICS census — unscoped, all, and sector-scoped modes; 2026-09-09)

The vault's blind spots include companies it has never SEEN, which no amount of re-reading existing notes surfaces. Census the universe against coverage — per _shared/quartr.md (§1 loading; degrade with a ⚠️ Quartr unavailable — blind-spot screen skipped if the server is down):

1. Pick the 1-3 densest sectors in scope (by active+monitoring thesis count — unscoped modes; sector-scoped mode uses its sector). Map each to Quartr GICS industry name(s) (e.g. vault semiconductors → "Semiconductor Materials and Equipment" + "Semiconductors").
2. list_companies {gics, countries, marketCaps} — countries chosen from where the vault's edge in that sector actually lives (the book's semicap coverage is KR/TW/JP/EU-heavy; a US-only census misses the point), market caps from the tier the vault hunts in (typically Small/Micro for new ideas, since Mega-caps are rarely blind spots). Cap: ≤3 GICS queries per run, ≤2 pages each.
3. Diff the returned companies against vault coverage: thesis tickers (any status) + Watchlist.md tickers. The residue is the coverage gap: names in the vault's densest hunting ground that it has never looked at (validated live 2026-09-09: the KR/TW/JP semicap small-cap census returned 13 names of which the vault covered ~4 — Tazmo, Wonik QnC, Techwing, Tri Chemical, AIMECHATEC et al. were unexamined).
4. Output: a ### Coverage gaps subsection in the Phase 4 note — company, country, market-cap tier, Quartr link — as raw census. A gap name is NOT automatically an opportunity: to be promoted into Phase 3 it must still clear the ≥2-cross-note-datapoint bar (e.g. a gap company that is a named supplier/customer in an existing thesis's value chain, or sits on a fired mental-model trigger). Unpromoted names stay in the census list for the user to eyeball — the census's value is making the unexamined visible, not manufacturing theses.

Phase 3: Opportunity Generation

Generate 3-5 specific, actionable research prompts ranked by potential conviction impact:

For each opportunity:

• Topic: What to research
• Why now: What triggered this being relevant
• Vault connection: cite ≥2 specific cross-note datapoints (name the notes) that, connected, produce the insight — a single-note observation is a summary, not a surfaced connection. The vault's edge is correlating optically-insignificant datapoints across notes (CLAUDE.md); an opportunity that rests on one datapoint or a generic theme fails this bar.
• Model trigger: the mental-model trigger the opportunity rests on, cited by stable ID ([G-#] / Industry # / Lens §) or none. Binds the mandated Mental-Models read to each idea (per-opportunity, not one global gate check); when ≥2 sources point the same way, treat the agreement as a trigger to disconfirm (READING PROTOCOL), not to commit.
• Falsifier: the single observable that would prove this opportunity ISN'T real (READING PROTOCOL — every surfaced idea is a hypothesis; name what kills it). An opportunity with no falsifier is a narrative, not a testable idea.
• Priced-in check: whether the market already prices this — already consensus / partially priced / genuinely non-consensus — [what the market currently assumes]. Source it from the relevant sector note's Investor heuristics section (already in the Phase 1 read set). An opportunity the market already prices has no edge even if true; this field makes that explicit per idea.
• Expected impact: High/Medium/Low potential to change a conviction level
• Suggested approach: Specific research steps

Targeted deep read before saving (default section-targeted mode). Default mode skips each thesis's Business Model & Product Description and Industry Context (Phase 1) — the likeliest home of the cross-company linkage an opportunity rests on. Once an opportunity is generated, do a TARGETED read of those two sections for ONLY the tickers it implicates (not the whole portfolio) to pressure-test the connection before saving. Keep it targeted — implicated tickers only; a portfolio-wide back-fill would defeat the mode's read budget.

Phase 4: Output

Save findings to:

• Unscoped default: Research/YYYY-MM-DD - Insight Surface Scan.md
• Unscoped all: Research/YYYY-MM-DD - Insight Surface Scan (all).md
• Ticker-scoped: Research/YYYY-MM-DD - [TICKER] - Surface Scan.md
• Sector-scoped: Research/YYYY-MM-DD - [Sector] - Surface Scan.md

If the file already exists, append a counter (...2.md, ...3.md). Save with:

---
date: YYYY-MM-DD
tags: [research, meta, surface-scan]
status: active
source: vault synthesis
source_type: synthesis
scope: default | all | ticker:TICKER | sector:[Sector]
propagated_to: []
---

The scope: frontmatter field records which mode produced the note — lets downstream review (and /lint) distinguish a routine section-targeted scan from a deep all scan or a scoped run.

Why propagated_to: []: Surface scans are exploratory portfolio-level metadata, not per-thesis evidence. Their body wikilinks reference many theses for context, NOT to claim each one needs a Log entry. The empty list is a terminal dedup signal to /sync Check 2 — the producer skill (this /surface run) explicitly declares "no propagation needed." Without this, the next /sync would treat each body wikilink as a propagation target and spam Log entries across 10+ theses with shallow scan-derived insights. See /sync Step 1 Check 2 for the empty-list semantics.

Graph update deferred: _graph.md is now owned exclusively by /graph. After this skill, run /graph last to register the surface scan research note, new cross-thesis connections, and any implied-but-unwritten thesis candidates in the dependency map.

Update _hot.md (read first, then edit — do NOT touch Latest Sync or Sync Archive, owned by /sync):

1. Active Research Thread: Same-ticker continuation — if the current thread already covers the same primary ticker/topic, append a dated line (YYYY-MM-DD: [update]) to the existing thread instead of compressing. New topic: compress the outgoing thread into a single *Previous:* entry (date + one-phrase summary). Write: surface scan completed [scoped/unscoped], top insight found, and the logical next research step. Append *Previous:* line(s) — max 5, drop oldest.
2. Open Questions: Add any critical blind spots or research gaps the scan exposed

Word cap: After all _hot.md edits, check total word count. If over 8,000 words (soft cap per _shared/hot-md-contract.md), prune ## Sync Archive entries (oldest first), then *Previous:* lines in Active Research Thread (oldest first), until under cap. If over 10,000 (hard cap), abort _hot.md update per contract.

Note body carries every Phase 3 field per opportunity — the Falsifier is mandatory in the saved note, not just the chat report. If opportunities are rendered as a table, Falsifier is a required column; if as prose blocks, each opportunity ends with its Falsifier: line. A surfaced idea whose falsifier survives only in chat is unfalsifiable by the time anyone re-reads the note.

Trigger-utilization rollup (report section). Add a short section to the report summarizing which mental-model lenses fired across this run's opportunities (from the Phase 3 Model trigger fields). A lens that NEVER fires across any opportunity is a blind spot — the vault isn't looking through it; a lens that fires on EVERYTHING is decoration — it isn't discriminating between ideas. This is a meta-signal on the reading gate itself: the utilization pattern audits whether the Mental-Models read is doing analytical work or just being ritually cited.

Write actionable opportunities to the open-findings register (_followups.md at vault root — durable ledger, _shared/followups-contract.md). Read the file first (auto-created by the first writer if absent). For each Phase 3 opportunity ranked worth a concrete next skill (/thesis, /deepen, /ingest, /stress-test), append ONE entry to ## Open (prepend under the heading — newest first):

- [ ] YYYY-MM-DD · surface · [[Theses/TICKER - Name]] · <opportunity one-liner>, <suggested skill> → user acts or dismisses · src [[Research/YYYY-MM-DD - Insight Surface Scan …]]

Use portfolio in place of the thesis wikilink for cross-ticker opportunities (blind spots, supply-chain correlations). Only genuinely actionable opportunities — never routine scan output.

• Dedup (mandatory): grep ## Open for a surface · entry on the same thesis/opportunity; if present, update its date instead of stacking a duplicate.
• Soft cap: if ## Open exceeds 50 entries, surface ⚠️ _followups.md over 50 open entries — review/resolve backlog in the report; never auto-drop open entries.
• Resolvers /status and /sync close entries later; surface only appends.
• Non-fatal: on register write failure, report and continue — the Research note and _hot.md update are unaffected.

Also report a concise summary to the user highlighting the top 3 most actionable insights.