agentleFS
ahmadrishiahmadrishi/agentic-mahoraga/skills/guard/surface-assumptions/SKILL.md

surface-assumptions

Skill1 starsChanged 15 days agoMITView on GitHub

Use before implementing anything ambiguous — state the assumptions you are about to bet on, present competing interpretations instead of silently picking one, flag a simpler approach when you see it, and never take the spec's framing about the codebase's current state on faith (grep to confirm before acting). Distinguish assumptions you verified on disk from ones you are carrying forward unverified. Do NOT use for the full verify-current-state drill on a restore/re-add task (that is reuse-before-create) or for proving your change works after you build it (that is verification-before-advance).

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before implementing anything ambiguous or under-specified.

    line 20
  2. Distinctive:

    When a spec has more than one plausible reading.

    line 21
  3. Distinctive:

    When you spot a simpler approach than the one implied.

    line 22
  4. Distinctive:

    When the spec says restore / revert / re-add / add X — verify X isn't already there.

    line 23
  5. Distinctive:

    State assumptions explicitly: Write down what you're taking for granted.

    line 28
  6. Distinctive:

    Present competing interpretations: If the spec reads two ways, name both and say which you'll act on and why — don't choose one in silence …

    line 30
  7. Very specific:

    Flag a simpler approach: If one exists, say so and push back when warranted (→ simplicity-first).

    line 32
  8. Distinctive:

    Not flagging a simpler approach you noticed because "the spec said to do it this way."

    line 75

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Surface Assumptions

The cheapest defect to prevent is the one you catch before writing code, by naming the assumption you are about to bet on. Models fail here by hiding confusion, silently choosing one of several readings, and taking the spec's framing on faith. The rule: state assumptions, present interpretations, verify the codebase's actual state — don't guess quietly.

When it triggers

  • Before implementing anything ambiguous or under-specified.
  • When a spec has more than one plausible reading.
  • When you spot a simpler approach than the one implied.
  • When the spec says restore / revert / re-add / add X — verify X isn't already there.
  • Whenever something is genuinely unclear and the answer changes the outcome.

The rule

  1. State assumptions explicitly. Write down what you're taking for granted. If uncertain and it changes the outcome, ask rather than pick silently.
  2. Present competing interpretations. If the spec reads two ways, name both and say which you'll act on and why — don't choose one in silence and hope.
  3. Flag a simpler approach. If one exists, say so and push back when warranted (→ simplicity-first).
  4. When something is unclear, stop, name what's confusing, and ask. A precise question is cheaper than a wrong implementation.
  5. Don't trust the spec's framing about current state. "Restore / revert / re-add / add X" describes an intended end-state, not proof X is missing. Grep for X first. If it's already present and wired, don't re-add it (you'll duplicate it and may break the build) — verify it works and report the mismatch. (The full drill is in reuse-before-create.)
  6. Label verified vs unverified assumptions. Separate "I grepped and confirmed X on disk" from "I'm assuming X" — the reader must know which claims you checked.

Key points

  • Surfacing ≠ asking. Writing an assumption into your notes is good, but when the assumption is load-bearing and unverified, do both: verify what you can (grep), and ask about what you can't.
  • The autonomy slider. Strong, verifiable success criteria let you proceed without asking; genuine ambiguity that changes the deliverable warrants a question. Calibrate: don't ask about trivia you can resolve by reading the code, and don't silently guess on a fork in the requirement.
  • A caught spec-vs-reality contradiction is a valid, high-quality result — often a no-op plus a report — not a failure to produce a diff.

Worked example

Spec: "Re-add the export button that was removed last sprint."

  • Assumption to check: was it actually removed? Grep the button / its handler / its registration → it's still declared and wired at the fork-point.
  • Correct move: report "Export button already present and wired at the fork-point — verified it renders and fires; re-added nothing" — a valid no-op — rather than adding a duplicate that breaks the build. Silently "re-adding" it on faith would have shipped the bug.

Second example — competing interpretations. Spec: "Add caching to the report endpoint." Readings: (a) an HTTP response cache with a TTL; (b) an in-memory memoization of the expensive query; (c) a per-user cache. They differ in correctness and invalidation. Correct move: name the three, state which you'll do and why (or ask), instead of silently picking one and discovering later it served stale per-user data.

Anti-patterns

  • Silently picking one interpretation of an ambiguous spec and hoping it's the intended one.
  • Taking "restore / re-add X" on faith without grepping the current state first.
  • Hiding confusion and guessing rather than naming what's unclear.
  • Not flagging a simpler approach you noticed because "the spec said to do it this way."
  • Presenting an unverified assumption as a confirmed fact.
  • Asking about trivia you could have resolved by reading the code (over-asking is its own failure).

Related skills

  • reuse-before-create — the full verify-current-state-first drill for restore/revert/re-add tasks.
  • simplicity-first — the simpler approach you should surface and push for.
  • verification-before-advance — turn a resolved assumption into a concrete success criterion, then prove it.
  • karpathy-guidelines — bias 1 (think before coding), in context.

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.