agentleFS
anivaranivar/agentic-sdlc/skills/thin-slices/SKILL.md

thin-slices

Skill0 starsChanged 37 days agoMITView on GitHub

Land work as thin, complete, reviewable slices: one pull request per plan step, nothing half-done on the shared branch, scope held to the step, verification run once per change, staging by path with the index read before the commit, a go-ahead for every commit, push and post, no force push to a protected branch, no key-shaped literals, no secret ever printed, production read-only. This is the execution discipline the hook enforces. Triggers on: "implement the next step", "land this", "next step from the plan", "ship this slice", "ready to commit", "open a PR", "is it ready to merge", "what should I stage".

  • Reads credentials
  • Commits and pushes

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the glossary and the records that touch the area (decision-records), then implement the smallest complete piece.

    line 53
  2. Distinctive:

    Run the repository's own checks (TEST-5).

    line 56
  3. Distinctive:

    Commit on the go-ahead, with a first line that is short, imperative and standalone, and no tool attribution (ATTR-1).

    line 59
  4. Distinctive:

    Commit and pull request text follows the change-description rules plain-voice owns: a short, imperative, standalone first line.

    line 72
  5. Distinctive:

    No trailer names a tool (ATTR-1).

    line 88

≈ “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

Thin slices

Implement one piece, test it, verify it, show it, then the next. Each slice leaves the system working. The hook turns the git and forge rules below into mechanisms; the rest are the habits that keep a change small enough to review.

The rules

IdRuleIn practice
SLICE-1One change per step, reviewable in one sittingOne pull request per plan step, with clear acceptance. Around a hundred changed lines reads in one sitting.
SLICE-2Nothing half-done reaches the shared branchA step merges complete, with tests, docs and, where the repository keeps one, its changelog entry, or waits. Incomplete work stays behind a flag or on its branch.
SLICE-3Scope disciplineOnly what the step requires. Note adjacent cleanups, unused imports, old syntax; leave them for their own step.
SLICE-4Verify once per changeRun each check after a change that could affect it. A pass on unchanged code is not repeated.
SLICE-5Stage by path and read the indexgit add <path>; when another session may have touched a file, re-read git diff <file> and stage whole files by path, or the hunks with git apply --cached <patch>; read git diff --cached --stat before committing. Never git add -A (STAGE-1, hook deny).
SLICE-6A go-ahead per commit, per push, per postEach waits for its own yes. Approval for one does not extend to the next (ASK-1, ASK-2, ASK-3, hook ask).
SLICE-7Auto-merge only where allowedArmed only where the decider allowed it for that repository and branch. A merge to a release branch is a deliberate human act.
SLICE-8Fresh new files, confirmed deletionsCheck the path is absent before writing a new file. Check a file is untracked before deleting it, or get the deletion confirmed.
STAGE-1Stage by pathHook: git add -A, --all or -u without a narrowing path, a root pathspec such as ., and git commit -a are refused. git add -A src/ passes.
PUSH-1No force push to a protected branchHook: refused. A protected branch moves by merged pull request only.
PUSH-2Moving a tag is confirmed and explainedHook: asks, and says that every workflow triggered on tag pushes runs again and release assets may be rebuilt.
SECRET-1No key-shaped literalsHook: staged changes are scanned before the commit; CI runs TruffleHog. Tests generate keys at runtime; documentation samples use placeholders.
SECRET-2Never print a secretVariable name, file:line, length or hash. Exclude token-bearing lines before summarising a log. Never trust a masking regex.
PROD-1Production is read-onlyUnless the decider says otherwise for that action. The production targets are the ones docs/agents/conventions.md names.
REVIEW-6Confirm the diff is absent before mergingAnd re-diff a conflict resolution against the target's current file.
TEST-5Gate on exit codescheck && test, then the commit on its go-ahead, gated on the exit codes.
TRACE-1An untraceable gated command is confirmedHook: a command that mentions a commit, push, bulk add or forge write the parser cannot trace (a variable, an interpreter, an unusual wrapper) asks.
TRACE-2An untraced command is suspicious when configuredHook: with trace.untracked at ask or deny, a command the parser cannot trace to git, gh or glab gets that decision; a command made only of read-only programs passes.

The cycle

  1. Read the glossary and the records that touch the area (decision-records), then implement the smallest complete piece. Ask first what the simplest thing is that could work; three similar lines beat a premature abstraction.
  2. Run the repository's own checks (TEST-5).
  3. Show what changed, what it deliberately leaves out, and what is next, in the change-description form plain-voice owns.
  4. Commit on the go-ahead, with a first line that is short, imperative and standalone, and no tool attribution (ATTR-1).
  5. Next slice. Carry forward; do not restart.

Slicing

Vertical slices by preference: one complete path through the stack per slice. Risk-first when one piece is uncertain: prove it before building on it. Contract-first when two sides develop in parallel: the contract is slice zero. A feature that is not ready for users merges behind a flag with a safe default.

Commit text

Commit and pull request text follows the change-description rules plain-voice owns: a short, imperative, standalone first line; what the change leaves out; no identifiers in code or fixtures and full links for every reference (TICKET-3, TICKET-4). The signer is the operator of record: no tool trailer, no generated-with footer (ATTR-1).

A slice, end to end

  1. Plan step P2.3 says: "the search endpoint rejects a page token with 400". One slice.
  2. Failing test first (test-first), then the smallest handler change that passes it.
  3. just check exits 0. Nothing else in the tree changed (SLICE-3): a stray formatting fix in another file is noted for its own step, not included.
  4. Stage by path: git add src/search.py tests/test_search.py; read git diff --cached --stat.
  5. Say what it does, why, and what it leaves out: "Rejects a page token with 400 and a page_token_unsupported code. Pagination itself is still not implemented; that is P2.4."
  6. On the go-ahead: git commit -m "Reject a page token on search with 400" (-s where the repository requires a sign-off). The hook asks (ASK-1), the decider answers, the commit runs. No trailer names a tool (ATTR-1).
  7. On the next go-ahead: git push, a pull request with the same three sentences, the review from review-change, merge when the checks pass. Then P2.4.

Hooks and secret files

The repository's hooks run on every commit and push. Never pass --no-verify or commit -n, and never point git at another hooks directory or config, on the command line or through git config (GUARD-1); when a hook is wrong, the fix is a change to the hook in its own slice. A file that holds credentials by name (.env, a private key, .netrc, .npmrc, credentials.json, a PEM or keystore file) is not read, copied or sent without a go-ahead (SECRET-3); name the variable or the file's length or hash instead (SECRET-2).

Companion skills

NeedSkill
Tests for the sliceinvoke test-first
The review before mergeinvoke review-change
The plan step the slice implementsplan-project
The ticket it closescut-tickets

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.