01 — Framing: what problem the next tool actually solves

Date: 2026-05-26 Status: ratified 2026-05-26 23:22 by Pär ("yes to all"), with the explicit caveat that gaps may surface as we close in on an actual spec — re-anchor if so. Codex review applied: C1 implementation-leak fixed, C6 added (media coverage), M1 fact-provenance promoted to hard constraint, /cowork demoted from hard constraint. Inputs: omega-review-1 SYNTHESIS, omega-review-2 SYNTHESIS-forks (rev 2), Pars_view.md Q1–Q15 + captured section Purpose: lock in the problem statement before any "what to build / what to borrow" conversation. Everything downstream — fork choice, repo shape, what survives from gruvor, when to start, what the MVP looks like — must be measurable against the criteria stated here.

Pär's review-4 instruction: front-load discussion. Claude over-pads early phases and useful items end up in never-reached later phases. This document exists to ratify the goal before any phase plan can be written.

1. One-paragraph statement

The next tool is Pär's investigative substrate — a single working environment that supports a series of long-form investigations (mining today, other topics later), each producing newspaper-grade articles. It earns its keep by aiding the dig in the research phase: helping Pär look in more directions, keep track of what he already has, and surface connections across investigations that he would not have found otherwise. It is not a publishing system, not a knowledge graph for its own sake, and not gruvor with the rough edges sanded. It is a sibling to arebladet2 — prepped for integration into that ecosystem but able to grow into the integration over time, not retrofitted later.

2. What it is

• An investigation substrate. The unit of work is "an investigation" — Aura/Häggån next, more after. Each investigation has documents, entities, a timeline, sources, draft prose, fact-checks.
• One tool, many areas. Mining is one slice. Bolagsverket-ingest, doc walkthrough, timeline-of-everything, scoped doc browse are reusable for non-mining investigations.
• A research-phase aid first. The article is downstream. The tool's job is making the research before-and-during the article better than not having it.
• Connected over time. A growing personal database. A non-mining story discovering a mining link is the durable payoff and the design north star.
• Modular toward arebladet2. Built so the eventual data-layer merge with arebladet2 / chatarkiv / arebladetmail is grown into, not refactored to.
• Pär-driven, Claude-executing. Walkthrough is one mode, not the canonical methodology. Per-doc-type review-UI is the centre of gravity: Claude processes one sample, Pär validates N samples in a UI, the processor clears to run autonomously.

3. What it is not

• Not gruvor. Functions from gruvor are useful; implementations are not authoritative. Borrowing happens by reading the gruvor code as one of several reference implementations, not by starting from the gruvor repo.
• Not a CLI for Pär. A CLI for other tools to call is fine. A CLI as Pär's primary interface is a non-feature. Where Pär interacts, there is a UI; where there is a UI, it is useful, not a sign that points elsewhere.
• Not a publishing system. Article output graduates into arebladet/articles (today) → arebladet2 (when it exists). The substrate produces evidence, prose, fact-checks; the publishing pipeline is downstream.
• Not a knowledge-graph product. A KG layer may or may not exist; if it does, it serves the timeline + spatial filter + cross-investigation discovery, not its own surface area.
• Not bound to current article scope. The X92 story foregrounded beneficial-owner + dispens-anomaly; that pattern is unlikely to repeat. Building toward "last article's surprise" is the wrong shape.
• Not mining-only. Even if the first three investigations are all mining, the architecture must permit non-mining use cleanly (per-investigation isolation or per-investigation directory or whatever the right primitive turns out to be).

4. The six load-bearing capabilities

These are the criteria every downstream architecture decision is measured against. Each is anchored in a specific gruvor finding or Pars_view.md statement, not abstracted from first principles.

C1 — Timeline of all things, with spatial filter by area (not point)

Pär (Q2): "having a timeline of all things … is load-bearing to this kind of writing. Next article will be about Aura and Häggån and it will be even more important as it will also include the full history of exploration in the Viken cluster, so we need some kind of location (and that being an area not an exact point) for me to walk through."

Anchored in: gruvor's /timeline + /kb-timeline validated as "vital" (omega-1 §4); the timeline capability named as the single most consequential feature to preserve (omega-2 §6 Q1). Spatial-area filter is the new requirement Aura/Häggån introduces — gruvor only had point-based filtering. How the timeline is implemented (typed temporal edges in a KG, date-faceted events in Datashare, or a simpler model) is the central Fork B vs F decision in Section 02 and is not pre-decided here.

C2 — Per-doc-type review UI for ingest

Pär (Q11): "We could do some kind of walkthrough skill, and present the data in a UI for me to review before implementation … processing — both with AI and programmatically — and a review UI is probably the best way to get through a lot of data."

Pär (Q12): "Document side by side to what the database will ingest. Claude processes one document type and creates script for that document type going forward (when possible), review certain number of programmatic process of a document to clear it to run on its own."

Anchored in: the 30-hand-coded-loaders debt (omega-2 §2.3 / A2 finding); the walkthrough method being overstated as canonical (omega-1 §4, Pars_view Q11). This is the structural fix to ingest sprawl.

C3 — Scoped curated doc browse with 1-sentence explainers

Pär (Q4): "Find a doc to check something specific … a map of what documents I have regarding something (with a 1-sentence explainer in the UI) would have helped … 'all Bolagsverket docs for this company' would be more useful."

Pär (Q7): "for the massive files like the prospectus, it would have been good to reference the original but split it up per section for easier access."

Anchored in: the crunch-time docs gap; the manual_dropins messiness; viewer never close to good enough. This is not a search engine, it's a knowledge garden — scoped by entity ("all docs for company X"), each with a one-line explainer, with massive PDFs split per section while backlinked to the original.

C4 — Cross-investigation discovery via a connected database

Pär (Q9): "Dream is a single tool with different article areas I work on, with a connected database — working on a completely different story could find a random connection to a mining thing, building my own database of useful things that survive for a long time, and suddenly there is something I would not have found otherwise."

Anchored in: this is the durable payoff. Each investigation produces entities, documents, events that survive past article ship. The substrate's value compounds over investigations the way gruvor's value did not (because gruvor was single-investigation by construction). Modular toward arebladet2 integration so chatarkiv + arebladetmail eventually feed the same connection-finding layer.

C5 — Media coverage and press articles as first-class entities

Pär (Q8): "The entire Viken area is covered in prospecting … the storyline is much longer, and involves a lot more people, and the media articles will be more important along the way."

Pars_view.md captured: "Media coverage / press articles as first-class entity — Aura/Häggån needs it; X92 didn't."

Anchored in: gruvor had a /media scaffold route with minimal traffic — not because media is unimportant but because the X92 story launched from a single company anomaly. Aura/Häggån is different: historical media coverage of the Viken cluster is source material for the investigation, not a nice-to-have. The substrate must store, link, and retrieve press articles as entities in the same space as regulatory docs and company filings.

C6 — Ingest is permissive, not topic-gated

Pär (Q7): "when I download documents, something might not be useful to this particular article, but I am thinking this might be something later, and should be able to ingest it logically without Claude saying this is not related."

Anchored in: gruvor's filtered-to-8-kommuner posture made future-broadening expensive. The substrate's ingest must accept "I don't know yet what this is for" as a valid intent, with a place for it to land that is not "the current investigation's folder."

5. Hard constraints

These are non-negotiable boundary conditions that constrain the architecture:

• UI must be useful, not point elsewhere. No UI feature whose payoff is "go read this in your editor." (M2 from omega-1, the 📓 Dossier card rage incident.) This is so basic that needing to state it as a rule is a warning sign about prompt-driven UI generation; state it anyway.
• No mining-specific assumptions in the platform layer. Per-investigation isolation must be cheap. A "mining area" config or a "this loader only runs on mining corpora" assumption is a future-cost.
• Bolagsverket-ingest as first-class reusable function. The most concrete reuse case Pär named (Q13). Whatever shape ingest takes, Bolagsverket pulls graduate as a clean, callable, non-gruvor-specific function — usable from other arebladet-family tools.
• Public spatial/permits data goes to gruvkartor.se, not here. Spatial primitives the substrate consumes are fine. The substrate is not where gruvkartor's data lives.
• No CLI as primary Pär surface. CLI for other tools to invoke = OK. CLI as the way Pär does anything = anti-pattern.
• Modular for arebladet2, not built into arebladet2 yet. Sibling repo. Shared-data-layer integration grows over time. No upfront merge.
• Factual interpretations must be computed or cited, not characterised. (M1 from omega-1 §3 — the X92 dispens near-miss. "This looks routine" is not a finding; a duration comparison, precedent, or source citation is.) This is an architecture constraint: the tool must make it easy to attach provenance to any AI-generated interpretation, and no output workflow should produce authoritative-sounding assertions without that anchor.
• /cowork for build sessions on this substrate is a strong default, not an absolute constraint. Section 05 will decide whether it becomes global policy. Do not slip into unreviewed solo-Claude builds on a non-trivial new substrate, but this is not irrevocably pre-decided here.

6. Non-goals and what is explicitly deferred

State these so downstream sessions don't drift into them:

• No deploy target named yet. Local-only is fine for the MVP. VPS, public surface, multi-user — deferred.
• No KG-vs-Datashare-vs-OpenAleph commitment yet. These are building blocks the architecture can choose to use, not the architecture itself. The framing does not pick one.
• No graduation path to arebladet2 yet. Modular toward it. Actual data-layer merge is later work.
• No commitment to "blank repo" or "sliced-down gruvor" as the starting point. Pär (Q12): "No clear opinion here. Blank repo that can borrow from gruvor maybe?" This decision is the explicit subject of a later planning section (02-build-options.md).
• No commitment to walkthrough method as canonical ingest mode. It is one mode. Per-doc-type review UI is the centre.
• No first article story or shape locked in. Aura/Häggån (Q8) has no clear storyline yet; the substrate's MVP is sized to "support starting Aura/Häggån research," not "produce the Aura/Häggån article."

7. The framing question Pär put on the table

Omega-2 §6 Q5: "Is gruvor an investigation tool, or a building hobby that produces investigations as a side effect?"

Pär's answer in Q1: "It is an investigative tool. The building hobby part is fuel to keep the actual work project going. No numbers."

That answer constrains the framing meaningfully: the substrate's success criterion is whether it produces investigations, not whether it is fun to build, even though the building has to be sustainable enough that Pär keeps wanting to work on it. Two concrete consequences:

1. When the choice is "fun to build" vs "useful for the next investigation," "useful" wins. This is a guard against M3 (capacity-filling from a task list rather than need-filling from the next article).
2. When the build process is the only available work (mining minutia is boring, no investigation is in flight), the right move may be to study an existing tool (OpenAleph, Datashare, Aleph Pro, somebody else's pipeline) rather than write new code. "Worth looking into what we can adapt from others rather than build from scratch" (Pars_view footnote in omega-2 §6 Q5).

8. Acceptance signal for this framing

This framing is good enough to start designing against if, reading it back, Pär can answer yes to all of the following:

• This describes the tool I want, not a tool that sounds reasonable.
• Every capability listed (C1–C6) is something I would actually use in the next 3 months.
• Nothing important is missing.
• Nothing important is included that I do not actually want.
• The constraints section is binding on the next session, not advisory.

If any answer is no, this document gets revised before 02-build-options.md is written. Front-loading discussion is the explicit purpose; downstream sessions read this as the contract.

9. Next planning sections (not started, listed so the sequence is visible)

• 02-build-options.md — blank repo with selective borrowing vs sliced-down gruvor vs OpenAleph fork vs Datashare-anchored vs something else. Each scored against C1–C6 + the hard constraints. Decision oriented.
• 03-keep-borrow-lift.md — function-by-function: keep (Tier 1) / borrow-the-data (Tier 2) / drop (Tier 3) for gruvor, plus per-candidate evaluation for OSS lifts (Tier 1B: OpenAleph, gitscrape, FTM, etc.) and Datashare run-alongside posture. Translates Pars_view Q11 ("functions yes, implementations no") + the 02 borrow tiers into a concrete table. Each candidate scored against C1–C6.
• 04-mvp-scope.md — the minimum substrate to support starting Aura/Häggån research. Sized to "start the next investigation," not "ship the next article."
• 05-process-changes.md — the five named failure modes from omega-1 §3 (M1–M5) + Pär's process changes from Pars_view captured section. Which become global rules, which stay project-scoped, which become skills, which become hooks.

Each later section depends on this framing being accepted; if Section 1 changes, downstream sections re-anchor.