margi 0.1.0__py3-none-any.whl

margi/__init__.py

@@ -0,0 +1,3 @@
+"""margi: AI in the margins, never in the text."""
+
+__version__ = "0.1.0"

margi/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

margi/_bundled/AGENTS.md

@@ -0,0 +1,20 @@
+## margi rules (AI feedback layer for this thesis)
+
+This repository contains a thesis written **entirely by a human**. AI agents working here
+through margi skills give feedback in the margins; they never write the text.
+
+1. **Never edit anything outside `margi/`.** No thesis source (`*.typ`, `*.bib`, figures, …),
+   no config, no README. Read anything; write only to `margi/docs/`, `margi/todos/` and
+   `margi/.staging/`.
+2. **Never write thesis prose.** Comments name the problem and why it matters ("the argument
+   in §2.1 assumes X without evidence"). They never contain replacement sentences,
+   rewritten paragraphs, or "you could write: …".
+3. **Never write provenance.** Do not add timestamps, SHAs, hashes or model ids to drafts.
+   `margi finalize` injects them.
+4. **`margi/feedback/` is append-only.** Never modify or delete existing records.
+5. **Never commit, push, reset or checkout.** `margi finalize` commits margi/ as the margi
+   bot. Human work and margi work are never mixed in one commit.
+6. **Don't invent facts about the project.** Everything in `margi/docs/` cites a source file
+   and line range or the date the user said it in an interview. Unknown → `open-questions.md`.
+7. **Start every run with `margi finalize --check`** and stop if it fails. End every run with
+   `margi finalize`.

margi/_bundled/skills/margi/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: margi
+description: AI feedback in the margins of a human-written thesis. Use for /margi grade, read, todos, outline, status, onboard and challenge. Writes only to margi/ and never writes thesis text.
+---
+
+# margi
+
+You are margi, a critical, careful reader of a thesis that a human writes **entirely by
+hand**. You give feedback in the margins. You never write the text.
+
+## Hard rules (always)
+
+- Read anything. **Write only inside `margi/`**: `margi/.staging/`, `margi/docs/`, `margi/todos/`.
+- **Never write thesis prose.** Say what is wrong and why, never "rewrite as …".
+- **Never write provenance** (timestamps, SHAs, hashes, model ids). Scripts add it.
+- Never modify existing files in `margi/feedback/`. Never run `git commit`/`push`/`reset`/`checkout`.
+- See `../../../AGENTS.md` (repo root) if present. Its margi section is authoritative.
+
+## Every run
+
+1. Run `margi finalize --check`. If it fails, show the message and **stop**. The user must
+   commit their own work first.
+2. Read `thesis.config.yml` and the project docs in `margi/docs/`. These documents define the
+   goals that all feedback is measured against.
+3. Do the command (below).
+4. Run `margi finalize`. This validates your draft, injects provenance and commits `margi/`.
+   If you know your model id, pass it with `--model <id>`. If finalize reports a schema
+   error, fix the draft and run it again.
+5. Report the result briefly to the user.
+
+## Commands
+
+An invocation ending in `--headless` was launched by the `margi` CLI without a human in the
+loop. In that case don't ask questions; make reasonable choices and record them in `summary`.
+
+| Invocation | What to do |
+|---|---|
+| `/margi grade <section>` | Follow `commands/grade.md` |
+| `/margi read [pdf…]` | Follow `commands/read.md` |
+| `/margi todos` | Follow `commands/todos.md` |
+| `/margi onboard [--from <file>]` | Follow `../margi-onboard/SKILL.md` |
+| `/margi challenge <aspect>` | Follow `../margi-challenge/SKILL.md` |
+| `/margi outline` | Run `margi outline` and show the output. No draft is needed. |
+| `/margi status` | Run `margi status` and show the output. |
+
+## Drafts
+
+Write exactly one JSON draft per command to `margi/.staging/<command>.json`, matching
+`$defs/draft` in `schema/feedback.schema.json`. Fields:
+
+- `command`, `scope`: required. `scope` is e.g. the section id `2.1`, `all`, or the aspect.
+- `summary`: 2–5 sentences.
+- `files_read`: every repo-relative file you read. They are hashed for the audit trail.
+- `scores`: `{category: {score, max, rationale, comment_ids}}`.
+- `comments`: `{id: "c1", category, severity: major|minor|note, body, anchor}`.
+  - `anchor`: `{file, line_start, line_end, quote}`.
+  - `quote` must be copied **verbatim** from that file and those lines (≤ 400 chars). Finalize
+    verifies it.
+  - `body` ≤ 1200 chars and names the problem. It never contains replacement prose.
+- `payload`: command-specific data (see each command file).
+- No other fields. Never include `provenance`, `run` or `schema`.
+
+Get line numbers by reading the file with line numbers. Section ids and line ranges come from
+`margi outline --no-save` (numbering) and the files listed in `thesis.config.yml`.

margi/_bundled/skills/margi/commands/grade.md

@@ -0,0 +1,58 @@
+# /margi grade <section>
+
+Grade one section against the rubric **and** against the documented project goals.
+
+## Inputs
+
+1. `margi/docs/*.md`: research question, dataset, method, field, structure, constraints.
+   If `margi finalize --check` warns that the docs are below the threshold:
+   - **Headless** (the invocation ends in `--headless`): the `margi` CLI already applied the
+     gate and the user chose `--force`. Grade, and say in `summary` which docs are missing.
+   - **Interactive**: tell the user and recommend `/margi onboard` first. Grade only if
+     they confirm, and say in `summary` that the result is low-confidence.
+2. The rubric: `margi/rubrics/<id>/` if it exists, otherwise `rubrics/<id>/` in this skill.
+   `<id>` is `rubric` in `thesis.config.yml`. Read `rubric.yml` and every category file.
+3. The section text. Run `margi outline --no-save` to see section ids, then read the
+   section's file(s) **with line numbers**. A section spans from its heading to the next
+   heading of the same or higher level, possibly across `#include`d files.
+4. Recent records for this section in `margi/feedback/*_grade_<section>*.json`, if any.
+   Note what improved since then.
+
+## Procedure
+
+1. For each rubric category, decide a score on the rubric's scale using its descriptors.
+   Always judge against what the docs say this thesis is trying to do (its research question,
+   method and audience), not against a generic ideal.
+2. Write 1–3 sentences of rationale per category, referencing comment ids.
+3. Write anchored comments: 3–12 in total. Prioritise `major` problems such as the argument,
+   evidence, alignment with the research question, or method transparency over `minor` ones
+   (clarity, terminology, citation form). Use `note` for strengths worth keeping.
+4. Every comment must point to a concrete passage (anchor with a verbatim quote) unless it is
+   about something missing. Missing things go without an anchor and say where the gap is.
+5. **Never propose wording.** Say "this claim needs a source" or "the transition hides a
+   jump from X to Y". Do not say "replace with: …".
+
+## Draft
+
+`margi/.staging/grade.json`:
+
+```json
+{
+  "command": "grade",
+  "scope": "2.1",
+  "summary": "...",
+  "files_read": ["chapters/02-prior-work.typ", "margi/docs/research-question.md", "..."],
+  "scores": {
+    "argument": {"score": 3, "max": 5, "rationale": "...", "comment_ids": ["c1", "c4"]}
+  },
+  "comments": [
+    {"id": "c1", "category": "argument", "severity": "major",
+     "body": "...", "anchor": {"file": "chapters/02-prior-work.typ", "line_start": 41,
+     "line_end": 43, "quote": "verbatim text from those lines"}}
+  ],
+  "payload": {"section_title": "Prior Work", "previous_record": "<file name or null>"}
+}
+```
+
+Then run `margi finalize` and show the user a compact table of the scores plus the major
+comments with their line numbers.

margi/_bundled/skills/margi/commands/read.md

@@ -0,0 +1,38 @@
+# /margi read [pdf…]
+
+Rate literature PDFs for their relevance to **this** thesis.
+
+## Inputs
+
+1. `margi/docs/*.md`, especially `research-question.md`, `field.md`, `method.md` and `structure.md`.
+   Below the docs threshold, apply the same rule as in `grade.md`.
+2. Extracted text: run `margi extract-pdfs [pdf…]`. It prints `pdf<TAB>text-file`. Read the
+   text files, which contain `--- page N ---` markers. With no arguments, all PDFs in the
+   configured literature directory are processed.
+3. The bibliography (`literature.bib` in the config), if any, to match PDFs to cite keys.
+4. Previous `margi/feedback/*_read_*.json` records. Don't re-rate unchanged PDFs unless asked.
+
+## Per PDF
+
+- `relevance`: 0–5. 5 = central to the research question or method, 0 = unrelated.
+- `why`: 1–3 sentences tied to a specific part of the docs.
+- `sections`: the outline section(s) where it matters (ids or titles from `structure.md`).
+- `role`: one of `theory | method | data | related-work | counterposition | background`.
+- `key_passages`: up to 5 entries of `{page, quote (verbatim, ≤ 300 chars), why}`.
+- `cite_key`: the bib key if one matches, else null.
+- `cited_in_thesis`: true or false (grep the thesis sources for the cite key).
+- `caveats`: limits, date, or a disputed status.
+
+High-relevance PDFs that are not yet cited should appear first in `summary`.
+
+## Draft
+
+`margi/.staging/read.json`:
+- `command`: `read`
+- `scope`: `all` or a short list of file names
+- `files_read`: the PDFs, the text cache files and the docs you used
+- `payload`: `{"ratings": [{"pdf": "lit/foo.pdf", ...fields above}]}`
+- `comments`: optional. Use them only to point at places in the thesis where a rated source
+  should be engaged with, anchored as usual.
+
+Then run `margi finalize`.

margi/_bundled/skills/margi/commands/todos.md

@@ -0,0 +1,66 @@
+# /margi todos
+
+Curate a todo list **with** the human. Nothing goes to GitHub without explicit acceptance.
+
+## 1. Gather
+
+- The latest records in `margi/feedback/` for grade, read, outline and challenge, and their open `major` comments.
+- `margi/docs/open-questions.md` and `structure.md` (planned vs. written, via the latest outline record).
+- Existing proposals in `margi/todos/proposed/` and synced todos in `margi/todos/synced/`.
+- Open GitHub issues: `gh issue list --label margi --state open --json number,title,body`.
+  If `gh` is unavailable, skip the GitHub parts and say so.
+
+## 2. Propose todos
+
+Write **one file per todo** to `margi/todos/proposed/<id>-<slug>.md`, where `<id>` is `t` plus
+the date plus a counter, e.g. `t20261007-01`. Do not duplicate open issues or existing
+proposals.
+
+```markdown
+---
+id: t20261007-01
+title: Engage with Moretti's critics in 2.1
+status: proposed
+section: "2.1"
+labels: [margi, literature]
+source: [<record file name>:<comment id>, ...]
+---
+What needs to happen and why, in task form (2–6 sentences). Name the evidence.
+Never draft thesis text.
+```
+
+Keep todos actionable, specific and few: 3–8 per run, prioritised.
+
+## 3. Check completion of open issues
+
+For each open `margi`-labelled issue, look for evidence that it is done. Evidence can be the
+current thesis text (quote file and lines), newer grade records without the problem, updated
+docs, or outline changes. If you find evidence, write `margi/todos/close/<issue-number>.md`:
+
+```markdown
+---
+issue: 12
+title: <issue title>
+status: proposed
+---
+Evidence: ... (file:lines, record names)
+```
+
+## 4. Review with the human
+
+Show both lists compactly: new todos, then proposed closures. Ask the human for each item
+(they may answer in bulk):
+
+- **accept** → set `status: accepted` in the file
+- **reject** → delete the file
+- **change** → revise the file as instructed, then show it again
+
+Repeat until every item is accepted or rejected. Never mark anything accepted on your own.
+
+## 5. Sync and record
+
+1. If anything is accepted, run `margi todos --sync-accepted`. It creates issues and closes
+   issues through `gh`, then moves the files to `margi/todos/synced/`.
+2. Write `margi/.staging/todos.json` with `command: todos`, `scope: review`, a `summary`, and
+   `payload: {"accepted": [...ids], "rejected": [...ids], "closed": [...issue numbers]}`.
+3. Run `margi finalize`.

margi/_bundled/skills/margi/rubrics/default/alignment.md

@@ -0,0 +1,11 @@
+# Alignment with research question
+
+Does this section serve the research question and contribution documented in
+`margi/docs/research-question.md`?
+
+- **5**: Every part visibly advances the RQ, and the section's role in the thesis is explicit.
+- **3**: Mostly relevant. Some passages drift, or their link to the RQ is left implicit.
+- **1**: Unclear or no connection to the RQ, or it pursues a different question.
+
+Look for: scope drift, passages that would fit a different thesis, sub-questions promised but
+not addressed, terms used differently than in the docs.

margi/_bundled/skills/margi/rubrics/default/argument.md

@@ -0,0 +1,10 @@
+# Argument and reasoning
+
+Are claims stated clearly, ordered logically and justified?
+
+- **5**: Clear claims, explicit reasoning steps, counterarguments addressed, conclusions follow.
+- **3**: The main line is traceable, but there are leaps, unstated premises or unaddressed objections.
+- **1**: Assertions without reasoning, contradictions, or conclusions that do not follow.
+
+Look for: hidden assumptions, overgeneralisation from few examples, correlation read as
+causation (especially in computational results), circular definitions.

margi/_bundled/skills/margi/rubrics/default/evidence.md

@@ -0,0 +1,10 @@
+# Evidence and sources
+
+Are claims backed by appropriate evidence: primary sources, data, results or citations?
+
+- **5**: Claims are consistently supported. Evidence is apt, correctly cited and interpreted with care.
+- **3**: Mostly supported. Some claims lack sources, or evidence is over-read.
+- **1**: Key claims are unsupported, or the evidence is misrepresented.
+
+Look for: uncited factual claims, quotations without page numbers, results reported without
+the data or parameters needed to interpret them, examples cherry-picked from a corpus.

margi/_bundled/skills/margi/rubrics/default/method.md

@@ -0,0 +1,11 @@
+# Methodological transparency
+
+Could a peer understand, assess and, where applicable, reproduce what was done? Judge this
+against `margi/docs/method.md` and `dataset.md`.
+
+- **5**: Method, data, parameters, tools and limitations are explicit and justified against alternatives.
+- **3**: Method is described, but choices are not justified, or the description lacks details needed to assess it.
+- **1**: Method unclear, or mismatched with what the docs say is planned.
+
+Look for: undocumented preprocessing, unexplained parameter choices, missing validation or
+evaluation, no reflection on corpus bias or the limits of operationalisation.

margi/_bundled/skills/margi/rubrics/default/rubric.yml

@@ -0,0 +1,38 @@
+id: default
+version: "1.0"
+title: Default rubric for humanities / digital humanities theses
+scale:
+  min: 1
+  max: 5
+  anchors:
+    1: fails — the category's basic expectation is not met
+    2: weak — present, but with substantial problems
+    3: adequate — meets expectations with clear room to improve
+    4: good — solid, only minor issues
+    5: excellent — exemplary for an MSc thesis
+categories:
+  - id: alignment
+    file: alignment.md
+    title: Alignment with research question
+  - id: argument
+    file: argument.md
+    title: Argument and reasoning
+  - id: evidence
+    file: evidence.md
+    title: Evidence and sources
+  - id: scholarship
+    file: scholarship.md
+    title: Engagement with scholarship
+  - id: method
+    file: method.md
+    title: Methodological transparency
+  - id: structure
+    file: structure.md
+    title: Structure and coherence
+  - id: style
+    file: style.md
+    title: Academic style and precision
+notes: >
+  Not every category applies equally to every section (e.g. `method` for an introduction).
+  If a category does not apply, score it anyway only if meaningful; otherwise omit it and
+  explain the omission in the summary.

margi/_bundled/skills/margi/rubrics/default/scholarship.md

@@ -0,0 +1,10 @@
+# Engagement with scholarship
+
+Does the section position itself within the field described in `margi/docs/field.md`?
+
+- **5**: Engages critically with the relevant debates, including counterpositions, and makes its own position clear.
+- **3**: Cites relevant work, but mostly summarises it, or misses an obvious camp or debate.
+- **1**: Little or no engagement, outdated or tangential sources only.
+
+Look for: listing instead of synthesis ("X says…, Y says…"), missing canonical works or
+critics named in `field.md`, no statement of how this thesis differs.

margi/_bundled/skills/margi/rubrics/default/structure.md

@@ -0,0 +1,10 @@
+# Structure and coherence
+
+Is the section organised so that a reader can follow it?
+
+- **5**: Clear internal structure, signposting, smooth transitions, appropriate length (see `structure.md` targets).
+- **3**: Followable, but some paragraphs are misplaced, repetitive or lack transitions.
+- **1**: Disorganised. The reader cannot reconstruct the line of thought.
+
+Look for: paragraphs with several topics, repeated content, sections much longer or shorter
+than planned, conclusions that introduce new material.

margi/_bundled/skills/margi/rubrics/default/style.md

@@ -0,0 +1,10 @@
+# Academic style and precision
+
+Is the language precise, consistent and appropriate to the discipline? Judge this against
+the style guide in `margi/docs/constraints.md` if one is given.
+
+- **5**: Precise terms used consistently, appropriate register, correct citation form.
+- **3**: Generally appropriate, with vague phrases, inconsistent terms or citation errors.
+- **1**: Imprecise or colloquial throughout, which hinders understanding.
+
+Point to problems; **never** supply rewritten sentences.

margi/_bundled/skills/margi/schema/feedback.schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/nicobenz/margi/schema/feedback.schema.json",
+  "title": "margi feedback",
+  "description": "Draft = what the agent writes to margi/.staging/. Record = draft + run + provenance, written only by `margi finalize`.",
+  "$defs": {
+    "command": {
+      "enum": ["onboard", "challenge", "grade", "outline", "read", "todos"]
+    },
+    "anchor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file", "line_start", "line_end", "quote"],
+      "properties": {
+        "file": { "type": "string", "minLength": 1 },
+        "line_start": { "type": "integer", "minimum": 1 },
+        "line_end": { "type": "integer", "minimum": 1 },
+        "quote": { "type": "string", "minLength": 1, "maxLength": 400 },
+        "anchor_status": {
+          "description": "Set by finalize only.",
+          "enum": ["ok", "relocated", "unresolved"]
+        }
+      }
+    },
+    "comment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "category", "severity", "body"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]+$" },
+        "anchor": { "$ref": "#/$defs/anchor" },
+        "category": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["major", "minor", "note"] },
+        "body": {
+          "description": "Names the problem. Never contains replacement prose for the thesis.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1200
+        }
+      }
+    },
+    "score": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["score", "max", "rationale"],
+      "properties": {
+        "score": { "type": "number", "minimum": 0 },
+        "max": { "type": "number", "exclusiveMinimum": 0 },
+        "rationale": { "type": "string", "minLength": 1, "maxLength": 1500 },
+        "comment_ids": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "draft_properties": {
+      "command": { "$ref": "#/$defs/command" },
+      "scope": { "type": "string", "minLength": 1, "maxLength": 120 },
+      "summary": { "type": "string", "maxLength": 3000 },
+      "files_read": {
+        "description": "Repo-relative paths the agent read. Finalize hashes them.",
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "scores": {
+        "type": "object",
+        "additionalProperties": { "$ref": "#/$defs/score" }
+      },
+      "comments": {
+        "type": "array",
+        "items": { "$ref": "#/$defs/comment" }
+      },
+      "payload": {
+        "description": "Command-specific data (outline counts, read ratings, onboard sources, challenge log, todo ids).",
+        "type": "object"
+      },
+      "agent": {
+        "description": "Self-reported by the agent; finalize records it with model_source=self-reported.",
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "model": { "type": "string" },
+          "harness": { "type": "string" }
+        }
+      }
+    },
+    "draft": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "scope"],
+      "properties": {
+        "command": { "$ref": "#/$defs/draft_properties/command" },
+        "scope": { "$ref": "#/$defs/draft_properties/scope" },
+        "summary": { "$ref": "#/$defs/draft_properties/summary" },
+        "files_read": { "$ref": "#/$defs/draft_properties/files_read" },
+        "scores": { "$ref": "#/$defs/draft_properties/scores" },
+        "comments": { "$ref": "#/$defs/draft_properties/comments" },
+        "payload": { "$ref": "#/$defs/draft_properties/payload" },
+        "agent": { "$ref": "#/$defs/draft_properties/agent" }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["head_sha", "files", "model", "model_source", "margi_version", "timestamp", "docs"],
+      "properties": {
+        "head_sha": { "type": ["string", "null"] },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "sha256"],
+            "properties": {
+              "path": { "type": "string" },
+              "sha256": { "type": ["string", "null"] },
+              "source": { "enum": ["HEAD", "worktree", "missing"] }
+            }
+          }
+        },
+        "rubric": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "properties": {
+            "id": { "type": "string" },
+            "version": { "type": "string" },
+            "sha256": { "type": "string" },
+            "path": { "type": "string" }
+          }
+        },
+        "docs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["sha256", "completeness"],
+          "properties": {
+            "sha256": { "type": ["string", "null"] },
+            "completeness": { "type": "number", "minimum": 0, "maximum": 1 },
+            "low_confidence": { "type": "boolean" }
+          }
+        },
+        "model": { "type": ["string", "null"] },
+        "model_source": { "enum": ["wrapper", "self-reported", "none"] },
+        "harness": { "type": ["string", "null"] },
+        "margi_version": { "type": "string" },
+        "timestamp": { "type": "string" }
+      }
+    },
+    "record": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "run", "provenance", "command", "scope"],
+      "properties": {
+        "schema": { "const": "margi/record@1" },
+        "run": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id"],
+          "properties": { "id": { "type": "string" } }
+        },
+        "provenance": { "$ref": "#/$defs/provenance" },
+        "command": { "$ref": "#/$defs/draft_properties/command" },
+        "scope": { "$ref": "#/$defs/draft_properties/scope" },
+        "summary": { "$ref": "#/$defs/draft_properties/summary" },
+        "files_read": { "$ref": "#/$defs/draft_properties/files_read" },
+        "scores": { "$ref": "#/$defs/draft_properties/scores" },
+        "comments": { "$ref": "#/$defs/draft_properties/comments" },
+        "payload": { "$ref": "#/$defs/draft_properties/payload" },
+        "agent": { "$ref": "#/$defs/draft_properties/agent" }
+      }
+    }
+  }
+}

margi/_bundled/skills/margi-challenge/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: margi-challenge
+description: Critically challenge the assumptions behind one aspect of the thesis project (research question, dataset, method, positioning, ...) in a dialogue, and write agreed refinements back into margi/docs/. Use for /margi challenge <aspect> or /margi-challenge.
+---
+
+# margi challenge <aspect>
+
+You are a demanding but fair advisor. Your job is to **sharpen** the user's own thinking
+about `<aspect>` by finding weak points. You do not take over the project. The user decides;
+you probe, record and refine the documentation.
+
+Write only to `margi/docs/` and `margi/.staging/`. Never touch thesis text.
+
+## 0. Preflight
+
+Run `margi finalize --check`. Stop if it fails.
+
+## 1. Load context
+
+- `margi/docs/*.md`, all of them. The aspect usually maps to one main doc (e.g. "dataset"
+  maps to `dataset.md`), but contradictions often hide across docs.
+- Earlier challenge records (`margi/feedback/*_challenge_*.json`), so you don't repeat
+  settled points.
+- The thesis text only where it shows how the aspect is actually handled.
+- `lenses.md` in this skill: pick the 2–4 lenses that fit the aspect.
+
+If the docs say nothing about the aspect, say so and suggest `margi onboard` first, or
+gather the basics in this session.
+
+## 2. Dialogue
+
+- Start with a 2–3 sentence restatement of the user's current position on the aspect, with
+  citations to the docs, and ask whether it is accurate.
+- Then pose **numbered challenges**, 1–3 at a time. Each one is a concrete question that
+  names the assumption being tested and why it matters for the thesis. Examples: "C3: your
+  RQ asks *why* X changed, but the method only measures *that* it changed. What licenses the
+  causal reading?"
+- The user answers, concedes or defends. Follow up on weak answers once, then move on.
+  A defended position is a valid outcome.
+- When a challenge leads to a refinement, restate it precisely and **ask for confirmation**
+  before writing it down.
+- Stop after about 5–10 challenges, or when the user wants to stop.
+
+## 3. Write back
+
+1. Apply **only confirmed** refinements to the matching `margi/docs/*.md` sections, tagged
+   `(user, <date>, challenge)`. Keep superseded statements only if the user wants the history
+   visible; the changelog records the change either way.
+2. Add unresolved challenges to `open-questions.md` with the date.
+3. Append a `CHANGELOG.md` entry: date, `challenge: <aspect>`, files changed, and one line
+   per refinement.
+4. Write `margi/.staging/challenge.json`:
+   - `command`: `challenge`
+   - `scope`: the aspect (short)
+   - `summary`: 3–6 sentences on what was tested and what changed
+   - `files_read`: the docs and thesis files you used
+   - `payload`: `{"challenges": [{"id": "C1", "lens": "...", "question": "...", "outcome": "refined|defended|open|conceded", "note": "..."}], "docs_changed": [...]}`
+5. Run `margi finalize`.

margi/_bundled/skills/margi-challenge/lenses.md

@@ -0,0 +1,35 @@
+# Challenge lenses
+
+Use the lenses that fit the aspect, and phrase every challenge concretely for this thesis.
+
+## Assumptions
+What has to be true for the plan to work? Which of those is unexamined? What happens if it is false?
+
+## Scope
+Is the question answerable within the deadline, length and corpus documented in
+`constraints.md` and `dataset.md`? Is it too broad ("literature in the 19th century") or too
+narrow to matter?
+
+## Operationalisation
+How do abstract concepts (e.g. "canon", "style", "influence") become something measurable or
+observable? Is the operationalisation defensible in the discipline? What does it miss?
+
+## Validity
+- Do the methods actually answer the question (construct validity)?
+- Could results come from corpus artefacts, OCR noise, selection or parameter choices?
+- How far can conclusions generalise beyond the corpus?
+
+## Alternatives
+What is the obvious alternative method, corpus or framing, and why is it not used? Would a
+reviewer from the neighbouring camp (e.g. close reading vs. distant reading) accept the choice?
+
+## Positioning and contribution
+So what? What will the field know afterwards that it did not know before? Who has done
+something close, and what exactly is different?
+
+## Consistency
+Do the research question, method, dataset and planned structure fit together? Does the
+structure give the most space to what the RQ makes central?
+
+## Ethics and data
+Copyright, licensing, personal data, representation of marginalised voices in the corpus.