agentleFS
mystilleefmystilleef/spae-framework/skills/proposal/SKILL.md

proposal

Skill2 starsChanged 5 days agoMITView on GitHub

- Turn a task or problem into a reviewable proposal before implementation. - Refine a hand-edited or external proposal before planning or implementation. - Hand any downstream reader, human or agent, a proposal whose every claim merits building or proving. - Settle design, decisions, and limits from confirmed findings; leave no open question. - Write the target proposal, present it for review, and change nothing else: - Draft: a new ./<slug>-proposal.md. - Refine: the supplied proposal, in place. - Draft:…

17 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use audit.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • OpenAISkill

    audit

    Audit or critique a product flow, journey, workflow, funnel, onboarding path, checkout path, settings path, screen, or multi-step product experience by capturing screenshots first, then reporting UX, design, and accessibility findings inline from that evidence. Use Figma only when the user explicitly asks for a board. Use when the user asks to audit, review, critique, inspect, assess, analyze, evaluate, or give feedback on a product experience.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

21 rules. 0 are common, 16 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 15 edited versions we read keep these.

  • 16

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write the target proposal, present it for review, and change nothing else:

    line 29
  2. Distinctive:

    Every file except the target stays unmodified.

    line 63
  3. Distinctive:

    Read project instruction and architecture docs in full when present.

    line 64
  4. Distinctive:

    Read codebase sections narrowly.

    line 76
  5. Distinctive:

    Run planned experiments per Constraints.

    line 77
  6. Distinctive:

    Never reference conversation context, prior runs, or paths absent from the repository, such as deleted experiment directories.

    line 101
  7. Distinctive:

    Codebase fit: prefer existing patterns over new design.

    line 119
  8. Distinctive:

    Never prescribe rigs, recipes, pixel coordinates, key sequences, or tooling provisioning.

    line 129
  9. Very specific:

    Never emit Unverified, open-question, TODO, or follow-up sections.

    line 136
  10. Distinctive:

    Write scope: write only the target; never edit any other file.

    line 142
  11. Distinctive:

    Run one only when source and docs can't settle a decision.

    line 144
  12. Very specific:

    Keep each minimal, unattended, timeout-bounded, and confined to a mktemp -d directory outside the repository.

    line 145
  13. Distinctive:

    Use installed tooling only.

    line 148
  14. Distinctive:

    Autonomy: never ask the user for input mid-execution.

    line 152
  15. Distinctive:

    Version control and release: never propose or run git mutations, package publishing, or deployments.

    line 155
  16. Very specific:

    No further changes: after REPORT, stop; never implement the proposal.

    line 157
  17. Very specific:

    Every claim names something to build, preserve, decide, reject, or accept.

    line 175
  18. Very specific:

    Every Design claim passes the references/outcome-guide.md substitution test.

    line 178
  19. Distinctive:

    No experiment directory remains.

    line 189
  20. Distinctive:

    Keep prose terse while ensuring clarity.

    line 196
  21. Distinctive:

    Use lists and sub-lists for long sentences and dense paragraphs.

    line 199

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “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

Proposal

When to use

  • Turn a task or problem into a reviewable proposal before implementation.
  • Refine a hand-edited or external proposal before planning or implementation.
  • Hand any downstream reader, human or agent, a proposal whose every claim merits building or proving.

Goal

  • Settle design, decisions, and limits from confirmed findings; leave no open question.
  • Write the target proposal, present it for review, and change nothing else:
    • Draft: a new ./<slug>-proposal.md.
    • Refine: the supplied proposal, in place.

Input

  • Draft: task statement from the argument, the conversation, or a task-only file.
  • Refine: path to an existing proposal file.
  • Project instruction and architecture docs, when present—for example AGENTS.md, CONTRIBUTING.md, README.md.
  • Codebase sections the proposal touches.
  • references/PROPOSAL.md: section template.
  • references/prose-protocol.md, references/outcome-guide.md, references/verification-guide.md.

Workflow

Select path by argument:

  • Refine: argument names an existing file holding a proposal.
  • Draft: otherwise; a file holding only a task statement supplies the task.
  1. GATE—Make no writes:
    • Select Draft or Refine; set the target:
      • Draft: derive a kebab-case <slug> from the task; target ./<slug>-proposal.md; confirm it doesn't exist.
      • Refine: target the supplied file; read it in full.
    • Inside a git repository, record git --no-pager status --porcelain as baseline.
    • Halt on any Halt conditions entry.
  2. ORIENT—State goal and path in one sentence:
    • Every file except the target stays unmodified.
    • Read project instruction and architecture docs in full when present.
  3. PLAN—Declare the work:
    • Refine: build a claim ledger—every claim in the target, with its rationale and section.
    • List investigation questions:
      • Draft: the task's unknowns.
      • Refine: open questions and claims needing source confirmation.
    • Name the codebase sections each question needs.
    • Name an experiment only for a question source and docs can't settle; state the decision it informs.
  4. ACT—Investigate, draft, refine:
    • Read codebase sections narrowly; widen only on uncertainty.
    • Run planned experiments per Constraints; delete their temporary directories afterward.
    • Draft: draft per references/PROPOSAL.md and Directives.
    • Refine: restructure the target per references/PROPOSAL.md and Directives.
    • Refine with confirmed findings; resolve every open question per Directives.
  5. VERIFY—Loop over Verification criteria:
    • For each failure: return to ACT, fix, then re-enter VERIFY.
    • Exit only when every criterion passes.
  6. PERSIST—Write the target—Draft: create; Refine: overwrite in place; re-read it to confirm the content.
  7. REPORT—Emit result following result directives and using result template; then stop.

Directives

  • Optimize for agent, token, and context efficiency.
  • Consult references/prose-protocol.md and references/outcome-guide.md before drafting.
  • Self-contained: readers, often agents, use the proposal for varied purposes, with no memory of this run or conversation; keep it self-contained, explicit, and token-dense:
    • Define non-standard terms on first use.
    • Never reference conversation context, prior runs, or paths absent from the repository, such as deleted experiment directories.
  • Claims become scope: downstream readers turn every claim into a requirement, test, or exclusion; write only what merits building, preserving, or proving. State Design as components, interfaces, and contracts; bind an internal choice through Decisions with its rationale, else omit it.
  • Condense, never drop (Refine): tighten wording; keep every claim and its rationale; move a discarded claim to Rejected or Accepted limits with a one-line rationale, never silently.
  • Evidence versus verification:
    • Evidence: how findings surfaced; downstream readers treat it as assumptions, never obligations.
    • Verification: outcomes the implementation must prove, each paired with its cheapest proving evidence.
  • YAGNI: discard unrequested scope, speculative design, and theoretical complexity; log each discard under Rejected with a one-line rationale.
  • Codebase fit: prefer existing patterns over new design.
  • Size: scale detail to task size; write None under a section without content; keep headers intact.
  • Proportional verification, per references/verification-guide.md:
    • Pair each outcome with the lowest evidence-ladder rung proving it, or prose with reading.
    • Require only tooling the repository already declares or installs.
    • File outcomes only a real GUI, browser, or native input can prove under Accepted limits; require such evidence only when the task explicitly asks or the repository already declares the tooling.
    • Never prescribe rigs, recipes, pixel coordinates, key sequences, or tooling provisioning.
  • Open questions: resolve each with prudent discretion—smallest scope meeting the goal; the conservative option when evidence stays insufficient:
    • Settle each into Design, Decisions, Accepted limits, or Rejected.
    • Never emit Unverified, open-question, TODO, or follow-up sections.
  • Plan boundary: omit delivery ordering, task decomposition, and implementation sequencing; leave them to whoever plans the work.

Constraints

  • Write scope: write only the target; never edit any other file.
  • Experiments:
    • Run one only when source and docs can't settle a decision.
    • Keep each minimal, unattended, timeout-bounded, and confined to a mktemp -d directory outside the repository; delete it before PERSIST.
    • Use installed tooling only; never provision tooling or build GUI or native-input rigs unless the task explicitly asks.
    • Isolate from the user's desktop, input devices, browser profiles, accounts, and live services.
  • Autonomy: never ask the user for input mid-execution; never propose steps requiring human execution, an attended terminal, or human presence.
  • Version control and release: never propose or run git mutations, package publishing, or deployments.
  • No further changes: after REPORT, stop; never implement the proposal.
  • Halt conditions: halt without writing; report Failed with a diagnostic under Findings:
    • Draft: no task supplied.
    • Draft: ./<slug>-proposal.md already exists.
    • Refine: target unreadable or empty.

Verification

  • The target exists, follows references/PROPOSAL.md section order, and complies with references/prose-protocol.md.
  • The target stays self-contained: no reference to conversation context, prior runs, or paths absent from the repository; non-standard terms carry definitions.
  • Refine: every claim-ledger entry maps to a target section, Rejected and Accepted limits included; no claim or rationale vanishes.
  • Every claim names something to build, preserve, decide, reject, or accept; no open question, Unverified item, TODO, or follow-up survives.
  • Every Design claim passes the references/outcome-guide.md substitution test; every bound internal choice sits under Decisions with its rationale.
  • Each Verification row names existing repository tooling and its ladder rung, or reading for prose; no new tooling, rig, recipe, coordinate, or key sequence appears.
  • GUI-, browser-, or native-input-only outcomes sit under Accepted limits, unless the task opted in.
  • Evidence imposes no obligation; no delivery ordering or task decomposition appears.
  • Section depth matches task size.
  • No experiment directory remains.
  • git --no-pager status --porcelain differs from the GATE baseline only in the target's entry.

Result directives

  • Minimum words. Maximum signal.
  • Keep prose terse while ensuring clarity.
  • Optimize prose for agent, token, and context efficiency.
  • Split actions, findings, and summaries into terse bullet points.
  • Use lists and sub-lists for long sentences and dense paragraphs.
  • Result contract: orchestrating agents parse Result; a missing, altered, or inconsistent result breaks orchestration.
  • End every run—completion, short-circuit, abort, or halt—with the result template as the final message; never end on progress narration.
  • Set Result to exactly one template literal, verbatim; report an abort or halt lacking its own literal as Failed, with the reason under Findings.
  • Emit the result template as live markdown—never in a code fence.
  • Output nothing outside the template.

Result template

<!-- prettier-ignore-start -->
### Execution Summary

- **Actions**:
  - [Terse list of actions taken]
- **Files**:
  - [Proposal path]
- **Findings**:
  - [Terse list of notable findings, risks, or halt diagnostics]
- **Summary**:
  - **Decisions**: [Terse list of key decisions]
  - **Accepted limits**: [Terse list of accepted limits and residual risks]

> **Proposal Status** • `[slug]`
> **Result**: [Drafted | Refined | Failed]
> **Impact**: [Terse impact statement]
> **Path**: `[target path]`
>
> _Review the proposal before planning or implementation._  _(unless failed)_
<!-- prettier-ignore-end -->

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.