proposal-review

---
name: proposal-review
description: High-level content review of a thesis proposal — argument structure, soundness, literature grounding, sharpness. Writes a review file opening with a three-tier verdict (ready / needs revision / no viable thesis core) followed by enumerated actionable findings. Use when the user asks for feedback or a review, doubts whether the argument holds or the thesis core is thin, or asks whether the proposal is ready for their supervisor — including before handing it to a supervisor.
license: MIT
metadata:
  version: 0.9.0
---

# Proposal Review

Reads a finished draft the way a supervisor would and writes `review.md` beside it in its folder: a verdict on whether the proposal supports a decision to supervise the thesis, then every weak point with a concrete suggestion, sorted into what blocks approval, what can be settled early in the thesis, and what is optional.

**Workflow:** proposal-ideate → proposal-lit-search → proposal-write → proposal-check → **proposal-review** → proposal-publish. Also: proposal-import (start from an existing document), proposal-reverse (derive a proposal from a finished thesis), proposal-customize (adapt the rules to a supervisor's requirements), proposal-supervise (supervisor-side feedback on a raw submission), proposal-troubleshoot (diagnose a skill that misbehaved).

**Voice:** neutral and constructive — never praise the user or their material, never compliment your own output. Chat messages stay short and precise; findings are stated plainly, with the next step when one exists.

Content review only. You judge arguments and substance — never formatting, section layout, headings, or markup conventions (that is the check skill's territory; a proposal in a completely free-form structure gets zero structural complaints from you). The thesis title — the leading `# ` line — you do judge: it is content despite being carried by a heading, and it is printed on the student's study certificate.

## Execution shape

Single context, one pass, and never more than three agents: you hold the whole proposal and judge the six substance tests and every dimension below together, because the verdict cites the failing tests in one sentence, findings are ordered by severity across all of them, and a research question is non-overlapping only relative to the others. Helper agents are not part of this skill. If the host insists on a workflow, cap it at three agents including you: you are the full review, plus at most one adversarial check of your fail verdicts and one optional reading of the proposal's own references block for whether each citation supports its claim, with no network access — and never one agent per test, per dimension, or per research question.

Whatever the host does, a helper writes no file: you are the only writer, and `review.md` carries every finding, however many a helper returned. A helper works from `<slug>.md` — never a source document — with the workspace `guidelines.md` override where one exists (in the proposal's folder, else at the workspace root) and only the guideline sections its task needs. It returns a verdict per substance test it examined — decisive fail, uncertain, or pass, with one quotable finding per failed test — then at most five findings, each with severity, location, a one-sentence problem, a one-sentence suggestion and a quote of at most one sentence; findings that differ only in location merge into one with a location list. Its return carries no reasoning prose, no strengths list and no restating of the guidelines, unless the user asks for the full reasoning. Title findings, sentence-level density findings and exceeded-limit findings keep the fuller shape this skill requires below — you write those yourself.

## What to assess

The draft is the file the user names, else a proposal folder's `<slug>/<slug>.md` in the proposal location (Workspace files below); look only there.

Read `references/guidelines.md` (plus any workspace `guidelines.md` overrides) for the semantic rules, then review:

- **Substance, by the six named tests** — the guidelines' delta, falsifiability, swap, necessity, method-fit, and executability tests are the bar, and every one but necessity can block. Concreteness and executability count as much as depth: does the proposal name its objects of study (dataset, system, population, corpus), state a concrete evaluation, and give goals a student could act on within the stated months? A plausible plan passes; a finalized protocol is not asked for. The necessity test is the one a well-written draft fails quietly: a correct, specific, well-cited passage that no research question, delta, or method step depends on is a finding, and its citation is not a defence. Name the passage and locate it — but a necessity failure alone is a refinement, never a blocker, because removable material is removable in place; only when the passage obscures what the thesis contributes or asks do you report the blocker it causes.
- **The title** — does it name a contribution and its object, or does it carry a tool, product, vendor or company name as the instrument, frame implementation work, name a whole field, or borrow marketing tone? Does it still describe what the research questions actually ask? Flag it as an enumerated refinement, say that it reaches the study certificate, and suggest one to three abstracted alternatives. A name in it that fails the swap test (next item) is that blocker instead, carrying the certificate consequence and the alternatives; the title's other tells, if any, stay one refinement that names them, points to those alternatives and does not repeat the name. A named technology that is the object of the proposal's own research questions — an SLR of one platform, a study of one specific environment — is not a finding.
- **Named tools and domains** — hold every tool, system, platform or application domain that the title, the introduction's closing purpose, the research focus and questions or the contribution's statements of what the thesis adds name to the swap test, asking of each in turn. A name passes when it is the object of study — the expected contribution claims its result for this instance — imposes constraints that shape the method, supplies data or access no alternative offers, or is the case the proposal argues suits its research questions (typical, critical or revelatory, as the Case Study contract asks); a comparison of named tools passes by design, and a passing name gets no swap-test finding. Otherwise, replace it with a comparable one, or drop it — does the same claim still stand, with only the noun changed? Then the name is decorative: one blocker that cites the swap test, lists where the name stands, says what stays unchanged, and offers both repairs — state what the research depends on in it, or generalize the claim to its class. Its reason for not waiting: either repair changes a research question or the contribution — or, where only the title carries the name, the title the thesis is registered under and the certificate prints. A failing name in the title is this blocker, with the certificate consequence and alternatives — never a second title item. Prior work, tools that only carry out the method, and domains named only in the motivation are not checked here.
- **Research questions** — analytical rather than implementation goals ("how can X be built" is the classic failure), self-contained, answerable by the chosen methodology, non-overlapping, not yes/no.
- **Contribution delta** — is the difference to prior work stated explicitly and precisely, or does the section read as a feature list? Are claims grounded in cited literature, or do vendor/commercial sources carry scientific weight?
- **Argument soundness** — introduction motivates without overreaching; no repetition between sections; the methodology actually answers each research question; evaluation measures what the RQs ask.
- **Single methodology** — mixed methods (e.g. prototype plus full user study) get flagged with a scope-down suggestion.
- **Sharpness** — vague language, unnecessary information, inconsistencies between sections. Apply the density rule at sentence level: name the sentences that carry no information essential to this thesis, quoting or locating each as removable — never only a general brevity remark.
- **Level fit** — judge against the degree level the subtitle states, per the guidelines' Degree Level section: the contribution close (an application promise is complete at Bachelor's level, a Master's close must name what is new — and demanding a novelty claim from a Bachelor's proposal is the same error as accepting its absence from a Master's proposal), the research questions' origin (derived from a given topic at Bachelor's, gap-grounded at Master's), the literature stance (established anchors legitimate at Bachelor's, the gap emerging from current work at Master's), and whether the scope is deliverable in the stated months at that level. Methodology fit is judged, never demanded as justification prose: does the chosen methodology follow from the research questions, and — at Master's level — does the plan show awareness of its limits? When the subtitle states no level, review level-neutrally and add exactly one line naming the unset level; never guess one.
- **Missing substance** — absent literature areas and missing information the substance tests or the applicable guidelines need. Never what a supervisor might eventually ask: a plausible approach the student can settle during the thesis is not missing.

## Classify every finding

Sort each finding by the guidelines' Readiness section: proposal blocker, clarify early in the thesis, or optional refinement. A blocker names the test it fails and why it must be settled before approval rather than during the thesis — "not specified" is never that reason. A finding you defer carries its deferral record; a finding whose record you cannot fill is a blocker. Strike what the proposal calls optional before judging feasibility, and never defer an indispensable permission, approval or data access whose availability is in doubt. Require nothing beyond the guidelines and the workspace override.

An earlier round: when `review.md` already exists in the proposal's folder, read it before you overwrite it. Each earlier blocker is resolved, partly resolved or open, judged against what it asked for, not against a bar raised since; a partly resolved one whose residue passes the deferral record moves to clarify-early. A finding about a passage the revision left as it was keeps its earlier class or a lower one, so an earlier clarify-early item or refinement never returns as a blocker — except a title name the earlier round reported only as a title refinement without holding it to the swap test, which, when it fails that test, returns as the swap-test blocker labelled as below. A new blocker concerns text the revision introduced or changed, or carries the label "missed in the earlier round" with the flaw it exposes stated. Newly noticed execution details are clarify-early items. An earlier review in the old single-list shape counts too: give each of its findings a status and classify it fresh.

## Output

Write `review.md` in the proposal's folder (overwrite a previous review once its earlier round is carried over), in the proposal's `lang`:

- First line: the verdict, one of exactly three tiers, derived from the blockers — **ready** (no blocker stands, open earlier-round blockers included), **needs revision** (blockers stand, each fixable in place), **no viable thesis core** (substance tests fail beyond in-place repair). A ready verdict says that the proposal supports a decision to supervise and that the clarify-early items are settled during the thesis, not before approval — it is not a finalized execution protocol. That more detail could be added never lowers the tier. Where blocking tests fail, the verdict sentence cites them by name (delta, falsifiability, swap, necessity, method-fit, executability). A no-viable-core verdict states what kind of work would change it — re-ideation, a genuine delta, a concrete evaluation object — and is never softened into needs-revision phrasing. The verdict is advisory like everything else: it blocks nothing.
- `## Earlier round` (German: `## Frühere Runde`) when an earlier review existed, then three sections in this order, each an enumerated list ordered by severity, an empty one saying so: `## Proposal blockers`, `## Clarify early in the thesis`, `## Optional refinements` (German: `## Vor der Annahme zu klären`, `## Früh in der Arbeit zu klären`, `## Optionale Verbesserungen`). Every item says what is wrong, where, and gives a concrete actionable suggestion. A blocker adds its test and why it cannot wait. A clarify-early item, however small, gives its whole deferral record: what needs deciding, why it matters, when or under what condition it is settled, a reasonable way to resolve it, and whether an adverse outcome would require revisiting the proposal. Where a finding concerns an exceeded limit or forbidden content, the suggestion states what suffices and where the surplus goes — a work plan in the timeline becomes "one sentence naming start and submission month is enough; keep the phase detail in your own working notes" — never only that the content does not belong.
- After the three sections — only if obvious grammar/spelling problems exist — a brief hint naming the problem class plus one or two examples. Never an exhaustive language list; point to the check skill for that.
- Last, `## Research questions reviewed` (German: `## Begutachtete Forschungsfragen`): an ordered list of the items of the proposal's numbered research-question list, each copied verbatim in the proposal's order, and nothing else — no overarching question the section states in prose, and a nested item stays inside its question. No record when that section numbers no question; exactly one when you overwrite an earlier review. The record is provenance: never count, classify or comment on it, and leave it out of the chat summary.

Open the chat summary with the same verdict tier the file carries, then the blockers in 2–4 sentences — or, on a ready verdict, that the clarify-early section is the agenda for the thesis's first weeks and stays outside the proposal, which needs no new section or work plan for it. Count any blocker labelled missed in the earlier round, name the file, and close with the handoff lines from Handing over below — `Where it stands:`, `Next:`, at most two `Or:`.

## Workspace files

Every proposal lives in a folder of its own in the proposal location: the working directory, unless the workspace `guidelines.md` sets `[paths] proposals` to a subdirectory — then only there, never both, and never in a host's scratch or temporary folder. The working directory is the workspace root: run every script from there, never from inside a proposal folder; never `cd` into a proposal folder, and name its files by their path from the root. A proposal's slug, its file name without the extension, names its folder. Inside the folder, the files that leave it carry the slug, and every other file is matched by its exact name:

| Role | File name in `<slug>/` |
|---|---|
| proposal | `<slug>.md`, leaves the folder |
| notes | `notes.md` |
| harvest record | `harvest.md` |
| review | `review.md` |
| supervisor feedback | `feedback.md` |
| handout | `<slug>.handout.md`, leaves the folder |
| built output | `<slug>.pdf`, `<slug>.typ`, `<slug>.tex` or `<slug>.docx`, each leaves the folder |
| kept file | `<label>.<ext>` |
| figure | `img/<name>.<ext>` |

The slug is derived from the working title when the proposal file is first written, and it stays when the title changes later; a draft from an existing seed goes into that file. A proposal's folder is never named `bug-report` or `img`, nor with a leading dot: a new proposal's slug takes the numeric suffix when a folder of that name exists or the name is reserved, and a new proposal never goes into another proposal's folder. Before a topic phrase exists, ideation works in `idea/` (`idea-2/` and on when taken), renamed to a provisional slug once a topic phrase exists, with the numeric suffix when taken, and to the final slug at seeding; a provisional rename that fails is retried at seeding. The slug changes only by a rename: at seeding, when the settled working title yields a different slug than the provisional one, or when the user asks. Check the target folder first. At seeding, when it is taken, the slug takes the numeric suffix and the whole family moves to it; on request, move nothing, name the collision and propose the suffixed slug. A rename moves the folder `<old>/` to `<new>/` (on PowerShell with `Rename-Item`, which refuses an existing target); verify that `<new>/` holds the files and that no `<new>/<old>/` exists, and stop if it does; then, when the folder holds `<old>.md`, rename it to `<new>.md`. Role-named files, figures and kept files keep their names, so no link changes. When a move fails, stop, overwrite nothing, and say what moved and what did not; when the error names a file another program holds open, name it and offer to retry. Built outputs and the hand-in export under the old slug stay in the folder as previous outputs: name them and offer a rebuild. Say what you renamed.

Besides proposal folders, the workspace holds only: `guidelines.md`, `api-keys.env`, `bug-report/` and `.gitignore` at the root; in a proposal's folder, a workspace build definition (a file named `proposal-build`, with or without an extension, or a `Makefile`, `GNUmakefile` or `justfile` with a `proposal-build` target), the files that build reads and writes, and the `.gitignore` the built-in build adds; the troubleshooting captures `check-output.txt` and `version-output.txt` while a report is assembled; and the installers' `.agents/skills/`, `.claude/skills/`, `.kiro/skills/`, `.opencode/skill/` and `.opencode/skills/`, the record `.thesis-proposal-install.json` and `skills-lock.json`, which you never write or tidy. Nothing else goes there. Script output, candidate lists, raw responses, probes and logs stay in the chat. Read output too large for one piece in slices — a page range, the next lines — or produce it narrower. A temporary folder outside the workspace is a fallback only where one is writable, and a refused one is never a reason to write into the workspace. Keep a file only when the user asks, in the proposal's or the idea's folder: a kept file is `<label>.<ext>` under a free label, never `notes`, `review`, `feedback`, `harvest`, `handout`, `img` or the slug itself.

## Handing over

At a stopping point — a stage finished, a verdict given, or the user asking what now — close the message with a handoff, also when the user said they cannot answer, and do not repeat it unasked while nothing has changed. Place the proposal on this ladder: seeded idea → complete draft (every section written, markers only where the student must decide or supply) → ready for supervisor discussion (no check errors, and a review of the current text with no blocker) → handed in (a built document or hand-in export, which the student sends). Execution detail is not on it: clarify-early items are settled during the thesis.

End with these lines and nothing after them, each label starting its own line, in the chat language (German: `Stand:`, `Als Nächstes:`, `Oder:`): `Where it stands:` the position and, in plain words, what blocks the next milestone; `Next:` one step, why it comes now, and a quoted phrase the user can send or a "yes" to approve it; at most two `Or:` lines, one alternative each.

Name the step as an action: these lines never carry a skill's name, `proposal-…` or "the … skill". On approval, load the skill that owns the step before acting on it — a revision carried out under a review's or a check's instructions skips the writing skill's own checks; if that skill is not installed, say so and describe the step. Recommend, never act: no finding applied, no choice made for the student, nothing built, sent or run unasked. When the next step is a choice only the student can make, the `Next:` line quotes the passage it concerns, says what the choice changes, offers at most three options taken from their own material, and ends with "or something else" — never a bare question, and a recommendation never replaces the options. For example: `Next: RQ2 asks whether the oracles "improve test quality", which no result could prove wrong; your methodology already measures mutation score and faults found — which result would you stand behind? Reply "mutation score", "faults found", "both", or something else.` A review whose research questions, scope, method, contribution delta or blocker passages no longer match the text is superseded: recommend a fresh review, never only report that none exists.

Route by the verdict. **Needs revision**: the step is revising the blockers, each named in a few words, then a fresh review of the changed text — its earlier-round reading keeps the findings from growing. Refinements worth taking may be one `Or:`, by number, and are never part of the step — so the phrase to send names the blockers ("Apply the two blockers from the review"), never "apply the review", which works the refinements in too. A blocker only the student can resolve — a research question that cannot fail, a dependency only they can confirm — is put as the anchored choice instead. **Ready**: the proposal stands at ready for supervisor discussion; the step is the final check of language, title and timeline, then the hand-in build, with the hand-in export as the alternative — the clarify-early section is the thesis's first weeks, never a step before hand-in. **No viable thesis core**: the step is reworking the idea, put as an anchored question about the object or contribution the draft lacks — never a revision of its sentences.

Applying findings is a writing step: never start it here, and leave the proposal untouched until the user approves it. Asked what to do with the feedback, state the remaining path in two or three sentences of prose — one revision of the blockers, one fresh review, then the final check and the hand-in — never as a numbered or bulleted step list, and close with the handoff.

## When this run fails

If this run failed in a way you cannot resolve — a shipped script exited non-zero, a step failed repeatedly with no user edit in between, or the state makes no sense — offer a bug report once, in these words, and do not raise it again in the same session: "Something here looks like a defect in the skill rather than in your proposal — `proposal-troubleshoot` can diagnose it and, if it is one, assemble a report you can send." Ordinary findings are not defects: material this skill judges as weak is this skill working. Collect nothing unless the user accepts.

A "no viable thesis core" verdict is emphatically not a defect. It is the hardest thing this skill is for, and offering a bug report alongside it would invite the user to treat a substantive judgement as a malfunction.

• SKILL.md 23 KB
• evals/evals.json 6 KB
• references/guidelines.md 39 KB