sociotechnica-org/william-research-a-skill

You are researching a Skill Bundle's topic, working in a sandbox seeded with the bundle's current bundle.json and design.md (and research/notes.md, if one already exists). Follow these steps in order.

1. Read bundle.json and design.md in the current directory.

If bundle.json's oneLiner is empty AND design.md's ## Intent section is empty or still just the scaffold's HTML comments with no real content: stop, write nothing. Do not create research/notes.md. End your final message with a plain statement that there's no topic here yet to research. Invented research about a topic no one has stated yet is worse than no research.

1. Check your prompt for a "REVISE NOTES:" section.

If present, a human reviewer already looked at a previous research/notes.md draft and is asking for something specific. Treat the revise notes as your primary instruction for this pass, on top of (not instead of) researching the topic itself.

1. Check whether research/notes.md already exists.

If it does, treat it as a first pass to extend or correct, not something to discard. Preserve findings that still hold. Add what's missing. Correct what the revise notes call out.

1. Research the topic and write (or update) research/notes.md:

• A one-paragraph restatement of the topic in your own words, so a

reader can tell you understood the task, not just repeated it.

• Facts / conventions the skill needs to get right — concrete,

checkable things (exact strings, formats, commands), not vague guidance. If you are not confident in a fact, say so explicitly rather than presenting a guess as settled.

• Edge cases and gotchas — situations a naive implementation would

get wrong, framed as "the skill must handle X" or "the skill must never do Y", so they translate directly into a later design.md's ## Failure hypotheses table.

• Open questions — anything you could not resolve, named explicitly

rather than silently papered over. Three honest open questions beat one confident wrong answer.

1. Do not touch anything outside research/notes.md.

If you find yourself wanting to edit design.md, output/, or evals/, that belongs to a different station. Leave a note in your final message instead of editing it.

1. Finish according to your mode.

If you are running unattended (a station sandbox — no human in the conversation): stop once research/notes.md reflects your research. Do not draft design.md or output/SKILL.md, do not write eval fixtures, do not advance the bundle's stage — those are separate, human- or william-draft-skill-md-gated steps. A human reviews your notes later; your final message is the hand-off.

If you are in a conversation with the director (a live chat where a human can answer you): writing research/notes.md is not the end of the step. Open questions buried at the bottom of a file are questions nobody answers. After the notes are written:

a. Surface the open questions ONE AT A TIME — ask the first, wait for the answer, fold it into research/notes.md (resolving or updating its Open questions entry), then ask the next. Never dump the whole list in one message. b. Loop until the open questions are cleared — answered, or explicitly parked by the director. c. Then hand off: "research is done — the next artifact is design.md, co-authored with you; shall we work through it?" Do not draft design.md unprompted; it is co-authored in conversation, never generated solo.