agentleFS
arthur-plautzarthur-plautz/research-toolkit/.claude/skills/proposals/SKILL.md

proposals

Skill0 starsChanged 4 months agoMITView on GitHub

Manages research proposals — new methods, implementation changes, approach shifts, validation strategies, or reference steering. Guides the agent through a structured discovery, confirmation, and formalization flow that produces a versioned proposal document under docs/proposals/. Also used to view and edit existing proposals.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 9 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every proposal is grounded in scientific evidence via /references before it is formalized.

    line 16
  2. Distinctive:

    Do not propose alternatives that have no reference support.

    line 54
  3. Distinctive:

    After presenting the alternatives:

    line 62
  4. Distinctive:

    Ask the user: "Do you want to formalize a proposal for one of these alternatives?"

    line 64
  5. Distinctive:

    If yes: ask which alternative (or let them describe their own) and proceed to Phase 2.

    line 65
  6. Distinctive:

    If no: the skill ends — the interaction was exploratory only, no document is created.

    line 66
  7. Distinctive:

    If the user references an existing proposal by name or ID, skip to Phase 4 (Edit mode).

    line 68
  8. Distinctive:

    After collecting answers, summarize the proposal in structured form and ask: "Does this summary reflect your intent?

    line 86
  9. Very specific:

    Write the proposal document to: docs/proposals/{proposal-id}.md

    line 95
  10. Very specific:

    Use the template at .claude/skills/proposals/templates/proposal.md.

    line 96
  11. Distinctive:

    Reframed as hypothesis: if neither of the above applies, rewrite the claim as an explicit hypothesis to be tested (e.g.

    line 102
  12. Very specific:

    Read the existing proposal from docs/proposals/.

    line 114
  13. Very specific:

    If the edit touches the Method or References sections, invoke /references to verify or expand the literature grounding.

    line 116
  14. Very specific:

    Update the Status field if appropriate (e.g., draft → active, active → implemented).

    line 118
  15. Distinctive:

    All proposals must follow this section order.

    line 124
  16. Very specific:

    Follow the /references table format.

    line 163
  17. Very specific:

    All proposals live in docs/proposals/

    line 175
  18. Very specific:

    When creating a new proposal, check if a similar one already exists before writing (Glob docs/proposals/*.md and scan titles)

    line 178

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Purpose

This skill governs how new proposals to the existing research are handled. A proposal is any suggested change to:

  • The algorithm or method (e.g., replacing RandomForest with a different Critic)
  • The implementation (e.g., refactoring a module, changing a pipeline step)
  • The experimental design or evaluation protocol
  • The validation strategy or statistical method
  • The theoretical framing or reference basis

Every proposal is grounded in scientific evidence via /references before it is formalized.

Always invoke /references before exploring any alternative — no alternative is credible without literature support, and the proposal document's References section must satisfy the /references citation policy.


When to invoke

  • User asks "what if we used X instead of Y?"
  • User questions the current approach and wants to explore an alternative
  • User wants to propose a change to implementation, method, or evaluation
  • User wants to view, update, or refer back to an existing proposal
  • Invoke explicitly: /proposals or /proposals edit <proposal-id>

Flow

The skill runs in five sequential phases. Each phase has a checkpoint — do not proceed until the checkpoint condition is met.

Phase 0: Discovery     →  invoke /references → ground the topic in literature
Phase 1: Confirmation  →  present alternatives → confirm user intent
Phase 2: Elicitation   →  enter plan mode → collect information via questions
Phase 3: Formalization →  write proposal document to docs/proposals/
Phase 4: Edit mode     →  (optional) read existing proposal → targeted edits

Phase 0 — Discovery (Prerequisite)

Trigger: User raises a topic, question, or doubt about any aspect of the research.

  1. Ask the user: "Does this need a literature review first, or is existing grounding (docs/references/, prior proposals) enough to work from?" Check docs/reviews/ for an existing review on this topic before asking — if one already covers it, offer to reuse it instead of asking. If the user wants a review, invoke /literature-review on the topic and wait for it to complete before continuing; use its References table as the literature base for the steps below instead of searching from scratch.
  2. Identify the domain of the question: method, implementation, evaluation, framing, or references.
  3. Invoke /references — pass the topic as context (or the review's References table, if Step 0 produced one). Let it search for relevant literature before any synthesis begins.
  4. Using the grounded references, enumerate the main alternatives available for this topic. Present them to the user as a short list with one-sentence justifications drawn from the literature.
  5. Do not propose alternatives that have no reference support. If no relevant literature exists, state that explicitly.

Checkpoint: At least one alternative is grounded in at least one peer-reviewed reference before proceeding.


Phase 1 — Confirmation

After presenting the alternatives:

  1. Ask the user: "Do you want to formalize a proposal for one of these alternatives?"
  2. If yes: ask which alternative (or let them describe their own) and proceed to Phase 2.
  3. If no: the skill ends — the interaction was exploratory only, no document is created.

If the user references an existing proposal by name or ID, skip to Phase 4 (Edit mode).

Checkpoint: User has explicitly confirmed they want to open a proposal before any document is created or plan mode is entered.


Phase 2 — Elicitation (Plan Mode)

Enter plan mode immediately after confirmation.

In plan mode, interact with the user to collect the information needed for all proposal sections. Ask targeted questions — do not ask for information you can infer from context. Suggested question sequence:

  1. Motivation: "What is the limitation or gap in the current approach that motivates this proposal?"
  2. Impact: "Which files, functions, or experimental stages would need to change?"
  3. Method details: "How would the alternative integrate into the existing pipeline? Are there known hyperparameters or tweaks to explore first?"
  4. Plan scope: "How would you describe the effort — is this a small tweak, a module replacement, or a larger architectural change?"
  5. References: "Are there specific papers you have in mind, or should we rely on what /references surfaced?"

After collecting answers, summarize the proposal in structured form and ask: "Does this summary reflect your intent? Shall I write the proposal document?"

Checkpoint: User approves the summary before the document is written.


Phase 3 — Formalization

  1. Generate a unique proposal ID using the format: YYYY-MM-DD-{topic-slug} (e.g., 2026-04-03-gp-surrogate-critic). The slug is 3–5 words in kebab-case describing the proposed change.
  2. Write the proposal document to: docs/proposals/{proposal-id}.md
  3. Use the template at .claude/skills/proposals/templates/proposal.md.
  4. Fill all sections — do not leave placeholder text. Every section must contain substantive content derived from the elicitation in Phase 2 and the references from Phase 0.
  5. The References section must follow the /references table format exactly.
  6. Before writing, audit every mechanistic or directional claim (e.g. "X improves Y", "increasing Z reduces W", "larger N leads to better Q"). Each such claim must satisfy exactly one of:

    • Cited: backed by a specific, verifiable claim in a peer-reviewed paper included in the References section — cite it inline with author/year.
    • Empirical: derived from a concrete result already observed in this project — state the metric and experiment it comes from.
    • Reframed as hypothesis: if neither of the above applies, rewrite the claim as an explicit hypothesis to be tested (e.g. "we hypothesize that...", "the expected effect — to be verified — is..."). Never state a hypothesis as fact.

    Claims that cannot be cited, grounded empirically, or honestly reframed as hypotheses must be removed entirely.

Announce the file path to the user after writing: Proposal written to docs/proposals/{proposal-id}.md.


Phase 4 — Edit Mode

Triggered when the user references an existing proposal by ID, filename, or topic.

  1. Read the existing proposal from docs/proposals/.
  2. Identify which section(s) the user wants to change.
  3. If the edit touches the Method or References sections, invoke /references to verify or expand the literature grounding.
  4. Apply edits using targeted replacements — do not rewrite the whole document.
  5. Update the Status field if appropriate (e.g., draft → active, active → implemented). No other bookkeeping is required — the Status field alone tracks where a proposal stands.

Proposal document structure

All proposals must follow this section order. No section may be omitted.

1. Motivation

Why is this change being proposed? What limitation, observed result, or research gap drives it? Be specific — cite concrete evidence (a metric, a result, a paper finding) rather than vague dissatisfaction.

2. Impact

Which parts of the code and research methodology must change if this proposal is implemented?

  • Code impact: list files, classes, or functions affected and the nature of each change (replace, extend, remove, add).
  • Methodology impact: describe how the research method, experimental design, or evaluation protocol is affected. Point to specific experiment conditions, training stages, or evaluation metrics that change.

3. Description

High-level description of what is being proposed. What does the proposed change do, and what is the expected outcome? This should be readable without deep technical knowledge — it is the executive summary of the proposal.

4. Method

The technical core of the proposal. This section must address three sub-questions:

Integration — How does the proposed alternative connect to the existing framework? Which existing interfaces/modules does it touch, extend, or replace?

How it works — Explain the alternative method clearly. Include the key algorithmic idea, any relevant equations, and the intuition behind it. Ground in the cited references.

Relevant tweaks and tests — What hyperparameters need exploration? What ablation experiments or validation tests should be run first to assess feasibility before full integration? Be specific: which experiment conditions, which environments, which metrics.

5. Plan

A brief, ordered list of implementation steps. Each step should be actionable and scoped. Include an effort estimate per step if meaningful.

Format:

1. [step description] — effort: low | medium | high
2. ...

6. References

Follow the /references table format. Every claim in the proposal that is not common knowledge must be backed by a cited paper or book. Do not include references that are not cited in the body of the document.


Proposal template

See .claude/skills/proposals/templates/proposal.md.


Naming and indexing

  • All proposals live in docs/proposals/
  • File name: {YYYY-MM-DD}-{topic-slug}.md
  • Status field values: draft, active, implemented, rejected
  • When creating a new proposal, check if a similar one already exists before writing (Glob docs/proposals/*.md and scan titles)

Synergy with other skills

SkillWhen to invoke
/referencesPhase 0 (always), Phase 4 edits to Method or References sections
/project-knowledgeWhen the proposal touches core algorithm/architecture — load full project context before eliciting Method details

References

#TitleAuthorsYearVenueRelevance
1Design Thinking: Understanding How Designers Think and WorkCross, N.2011Book. Berg Publishers. ISBN: 978-1847886361Grounds the discovery-confirmation-formalization flow in established design methodology; the three-phase structure (problem framing, concept development, specification) maps directly to Phases 0–3 of this skill
2Good Enough Practices in Scientific ComputingWilson, Bryan, Cranston, Kitzes, Nederbragt, Teal2017PLOS Computational Biology 13(6): e1005510. DOI: 10.1371/journal.pcbi.1005510Recommends maintaining a versioned record of design decisions and alternatives considered — the proposal document serves exactly this function for research-code decisions
3A Rational Design Process: How and Why to Fake ItParnas, D.L.; Clements, P.C.1986IEEE Transactions on Software Engineering 12(2): 251–257. DOI: 10.1109/TSE.1986.6312940Argues that formalizing design decisions after the fact — even when discovery is exploratory — produces more maintainable and communicable artifacts; motivates the formalization step (Phase 3) even for proposals born of informal discussion
4Best Practices for Scientific ComputingWilson, Aruliah, Brown, Chue Hong, Davis, Guy et al.2014PLOS Biology 12(1): e1001745. DOI: 10.1371/journal.pbio.1001745Defines the "make the change easy, then make the easy change" principle; informs the Plan section's step-by-step format and effort classification

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.