agentleFS
Sign inStart free
MagicJoshMagicJosh/ras/skills/spec/SKILL.md

spec

Skill1 starsChanged 9 days agoMITView on GitHub

Use when the user runs /spec or asks for a plan, or when the ras hook denied an edit to a risky path. Asks what is unknown, writes specs/current.md, stops for approval.

168 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use backprop, ios-clean and 10 more.

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.
  • JuliusBrusseeSkill

    backprop

    Bug → spec protocol. When a bug is found or a test fails, trace the cause, decide whether a new §V invariant would catch recurrence, append to §B. This is the one non-obvious thing SDD does that plan-then-execute doesn't. Triggers on test failure, bug report, post-mortem, or explicit user ask.

    Also in 4 projects that use this

  • Saqlain-811Skill

    ios-clean

    Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app. (gstack)

    Also in 5 projects that use this

  • Saqlain-811Skill

    ios-fix

    Autonomous iOS bug fixer. (gstack)

    Also in 5 projects that use this

  • bastosSkill

    ios-design-review

    Review iOS app UI/UX design quality using Apple's design principles and the Liquid Glass-era design language from WWDC25/26. Use when asked for a design review, UX critique, visual design assessment, or evaluation of an app's interface quality, design intent, alignment with the new Apple design system, or usability. Triggers: "design review", "UX review", "visual design critique", "review the UI", "does this design work", "evaluate this interface", "design feedback", "Liquid Glass review".

    Also in 5 projects that use this

  • ShreyRaviSkill

    plan-tune

    Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences (never-ask / always-ask / ask-only-for-one-way), inspect the dual-track profile (what you declared vs what your behavior suggests), and enable/disable question tuning. Conversational interface — no CLI syntax required.

    Also in 7 projects that use this

  • timurgaleevSkill

    document-generate

    Generate missing docs for a feature, module or project as tutorials, how-tos, reference and explanation.

    Also in 6 projects that use this

  • +2 more from Saqlain-811

The file

We split this skill into the rules it gives an agent

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

  • 0

    Common

    Most of the 145 edited versions we read keep these.

  • 5

    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 contract before you touch the files.

    line 8
  2. Distinctive:

    Read the code the request touches.

    line 12
  3. Very specific:

    Ask it all in one plain-text round.

    line 14
  4. Distinctive:

    Write the spec only after every question is answered.

    line 17
  5. Very specific:

    Write specs/current.md in the project root with these sections.

    line 18
  6. Very specific:

    Blast radius: search for every caller and every file the change touches.

    line 28
  7. Very specific:

    Work packages: only when the work runs in waves.

    line 29
  8. Very specific:

    Start the file with # Spec: <title>.

    line 32
  9. Distinctive:

    Edit loop: When a notice says the page changed, and before each republish, read the live page and merge its edits ("Spec pages" section).

    line 40
  10. Distinctive:

    Do not write project files with Bash or PowerShell to get around the gate.

    line 52

“Common” is measured: kept by at least 6 in 10 of the 145 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

Spec

Write the contract before you touch the files. Ordinary changes do not need one. Use it on request, or when the hook denied an edit to a risky path.

Steps

  1. Read the code the request touches. Trace the real flow. Do not ask what the repo can answer.
  2. Goals first. If the request names the change and how it should behave, ask nothing: go to step 4 and list your choices under Assumptions. Otherwise find what is still unknown about: the goal, who uses it, must-have versus nice-to-have, what is out of scope, constraints, and what done looks like. Skip what the request or the code already answers.
    • Ask it all in one plain-text round. Never use AskUserQuestion.
    • Number the questions. Under each, give your recommended answer after Recommended:.
    • End the round with: "Reply yes to accept all, or answer by number. Type /spar for a deeper round." Then stop.
  3. Write the spec only after every question is answered. Put what the answers left open under Assumptions. Never ask for approval while a question is open.
  4. Write specs/current.md in the project root with these sections.
  5. Writing the spec is your last action, apart from its page (below). Copy the Decisions lines into your message, then ask once, and stop: reply with exactly approve spec.

Sections

  • Goal: one line.
  • Decisions: at most 3 lines, each - <choice>. Rejected: <alternative>. Hard to undo: yes|no. Write "none" when the change has one obvious shape.
  • Proposed additions: details the user did not ask for. A table: Detail | Proposal | Why it matters. Keep each row short. Skip the section if there are none.
  • Acceptance criteria: each one is a check that can run, with its command. "Works well" is not a check.
  • Non-goals: what you will not do.
  • Blast radius: search for every caller and every file the change touches. One line per file: - `path`: what changes. Callers: `a`, `b`.
  • Work packages: only when the work runs in waves. - Wave 0: <package>. <detail>.
  • Assumptions: what you decided without the user, each with the default you took. Skip the section if there are none.

Start the file with # Spec: <title>. Put the goal line under ## Goal.

Spec page

A spec is small when it has no Trade-offs and no Security section, Blast radius lists at most 2 files, and it has at most 3 acceptance criteria. Other specs are medium or large.

  • Medium or large: load artifacts and publish the page as its "Spec pages" section says, before you ask for approval. Link it in your message.
  • Small: end the approval message with: "Want a page for this spec? Reply page, or approve spec to approve it as it is." Build the page only on page.
  • Edit loop. When a notice says the page changed, and before each republish, read the live page and merge its edits ("Spec pages" section). If edits were merged, list them, republish, and ask again for approve spec: the spec changed, so the old approval is gone.
  • A page comment is a question, never an edit or an approval. Only approve spec typed in the terminal approves.

Rules

  • Scale the size to the change: a typo gets 3 lines.
  • The user can reply ask me at any point before approval. Then ask about every Decision and Assumption, and rewrite the spec with the answers.
  • Bug fix: criterion 1 reproduces the bug. Run it before any fix and record that it fails. A check that passes before the fix proves nothing.
  • Structural change means a new module or service, a new data store or data flow, a changed interface between components, or anything hard to undo. For these, load architecture or distributed-architecture. Add a Trade-offs section: the options, the cost of each, your pick and why.
  • Risky change means auth, secrets, permissions, payments, personal data, deletes of data, or production. For these, load security-check before you write the spec. Add a Security section with the risks and the checks for them.
  • A new request in the middle of a task updates specs/current.md. That breaks the approval. Stop again for approve spec.
  • The user can reply skip spec to let edits through until the next prompt.
  • Do not write project files with Bash or PowerShell to get around the gate.

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.

Check your setup, free