agentleFS
Sign inStart free
matheusPavanelimatheusPavaneli/workbench/skills/write-handover/SKILL.md

write-handover

Skill1 starsChanged 44 days agoMITView on GitHub

Writes the non-technical note for a support ticket - symptom, cause, what changes, and numbered steps for QA - to .workflow/<KEY>/handover.md. Use for support, bug or incident tickets that a QA lead or the person who raised them has to read.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    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. Very specific:

    Write qa_steps as something a person can follow: Start from a state they can reach, name the exact input, and end with what they should …

    line 34
  2. Distinctive:

    Say what is not covered: If the fix addresses the reported symptom but not a related case the reporter may hit, that belongs here, not …

    line 43
  3. Distinctive:

    No jargon, no paths, no function names, no commit hashes: If it cannot be said without them, it is not understood well enough to hand over.

    line 48
  4. Distinctive:

    The scope is a fact, not a comfort: If you do not know how many users were affected, say that rather than implying it was few.

    line 52

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

write-handover

wb <args>    # wb not on PATH: python <this skill's directory>/../../lib/wb.py <args>

The audience is not engineering. A QA lead has to validate this without reading the diff, and whoever raised the ticket has to understand what happened without knowing the codebase exists.

Steps

  1. Read the ticket and the plan. .workflow/<KEY>/triage.json for what was reported and in whose words; sdd get <KEY> --section summary and --section evidence for what was actually wrong.

  2. Fill the handover block in sdd.json:

    Field
    symptom_plainwhat the reporter saw, in their words
    cause_plainwhy it happened, one sentence a non-engineer can repeat
    fix_plainwhat changes for them
    scopewho was affected, since when, how many
    workaroundwhat to do until it ships, or none
    qa_stepsnumbered steps, ending in the expected result
    release_noteone line, if the repo keeps a changelog
  3. Write qa_steps as something a person can follow. Start from a state they can reach, name the exact input, and end with what they should see. "Test the coupon flow" is not a step. "Apply coupon SUMMER24, expired yesterday → the order is refused with a validation message and no charge appears in Stripe" is.
  4. Render it. sdd handover <KEY> writes .workflow/<KEY>/handover.md for pasting into the ticket.
  5. Say what is not covered. If the fix addresses the reported symptom but not a related case the reporter may hit, that belongs here, not discovered later.

Rules

  • No jargon, no paths, no function names, no commit hashes. If it cannot be said without them, it is not understood well enough to hand over.
  • Do not claim a cause you could not demonstrate. "Under investigation" is a legitimate handover; a confident wrong cause is not.
  • The scope is a fact, not a comfort. If you do not know how many users were affected, say that rather than implying it was few.
  • Nothing beyond what is needed. Five short answers and the steps. No restating the ticket back, no apology, no summary of the summary.

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