@ervis/skills 0.1.0

package/skills/engineering/ticket-grooming/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ticket-grooming
+description: Groom a JIRA/GitHub ticket, issue, user story, or spec until a coding agent could build it with zero open questions. Plans the implementation to surface the decisions nobody made, checks the ticket's claims and unstated assumptions against the real codebase, works out whether this repository has already shipped something of the same shape and says so plainly when it has not, so novel work is called out as needing a spike rather than stamped ready. Traces invariants and entity lifecycles for the bugs that only show up in transitions, then writes a document separating what the business still has to decide from how it resolves in code. Use this whenever the user pastes a ticket, story, spec, or a link to one, or says things like "is this ticket ready", "groom this", "refine this story", "challenge this ticket", "poke holes in this", "is there enough context here to build this", or complains that a ticket is vague, a wishlist, UX-only, or missing business scope. Also use it before starting implementation work from a ticket the user did not write themselves.
+---
+
+# Ticket Grooming
+
+If the `simple-english` skill is available, follow it for everything you write for the user.
+
+A ticket is ready when a competent coding agent could implement it end to end without asking anyone a question. That is the only test, and it is harsher than it sounds: a well-written ticket that leaves one real decision open fails it, and a scrappy one that closes them all passes.
+
+Your job is to find the decisions nobody has made, settle what you can, and ask about what is left.
+
+## What the ticket owes you, and what it does not
+
+You have the repository. The schema, the endpoints, the call sites, the current behavior are all there to be read, and a ticket owes you none of it. Go and look.
+
+What the code cannot tell you is anything that exists only in someone's head: why the work is wanted, what a business term means here, what should happen in a case the system has never faced, what is deliberately out of scope, who ought to be allowed, what the business would accept as proof it works, whether an already-stored record is now wrong or merely old. That is the whole subject of grooming. Everything else, answer yourself.
+
+This one distinction does most of the work. Hold it while you read and the questions sort themselves: if the repo could settle it, settling it is your job, and asking instead is a round trip you chose to spend.
+
+## Finding what is missing
+
+Plan the implementation for real. Not code, a plan good enough to hand someone: what changes, what is new, what the data looks like, what the tests would assert.
+
+The moment you reach for a guess, stop. That guess is the finding. Gaps you walk into are real in a way that gaps recalled from a list are not, which is why this beats reviewing the ticket against a template. Keep going to the end, then look at how many guesses the plan is standing on.
+
+## What to check the ticket against
+
+Four things worth going after. They overlap, and which one pays off varies by ticket, so read them as places to look rather than steps to perform.
+
+**Claims, and the assumptions underneath them.** Tickets assert how things work today, and assertions written from memory drift from the code. Check them and cite what you find; a contradicted claim often invalidates the design built on it. Then go after what the ticket assumed without saying: "add a column to the export" assumes that data is in scope where the export is built, "let admins reassign ownership" assumes ownership is single-valued. Chase the load-bearing ones, the ones where being wrong collapses the ticket, not every premise.
+
+**Precedent, matched on properties rather than on features.** Precedent means this repository already ships something of the same shape: a decision made, reviewed, merged and left running, with every local constraint nobody wrote down baked into it. A known pattern or a library that could do it carries none of that, so it does not count. Ask what the change is underneath, then go find it. A contact form and a newsletter signup are unrelated features and one problem, an unauthenticated public write endpoint, which is what drags in rate limiting, spam, sanitisation and abuse logging. If one already ships, all of that is solved and none of it needs asking.
+
+Match on the properties that pull concerns behind them: reachable without auth, crossing a tenant boundary, taking user-supplied content, sending something outbound, running long or async, touching money or personal data, unbounded input, rewriting rows already stored. A ticket usually has several and the answer differs between them, so check each. Where one has precedent, follow it and say where it is; where the ticket diverges from it, the divergence is the question; where one is new here, the unknowns are in the code rather than the ticket and answering questions will not surface them, so say it needs a spike and what the spike has to find out. Confirm the precedent solved your actual problem and not one sharing its vocabulary: a hardened check on user-supplied URLs looks like what you need to let someone reference an image in an outbound email, but it guards connections the server makes, and that image is fetched by the recipient's mail client.
+
+**Invariants.** An abstraction guarantees things: what is always true, what must hold before a call, what a caller may rely on after. Work out which of them this change touches, then sort each into preserved, broken on purpose, or broken by accident. Only the last is a defect, and the ticket will rarely distinguish, because the author was thinking about the feature and not the guarantee. A break that turns out to be intended still belongs in the ticket, or the next reader files it as a bug.
+
+**Lifecycles, crossed.** Walk the subject through created, changed, disabled, deleted, restored, then walk everything it associates with through the same, and cross the two. This generates cases rather than recalling them, which is why it finds what no checklist does: the dashboard shared with a team whose owner is deactivated, the export in flight when its source is deleted, the schedule whose recipient lost access. Tickets describe the steady state; the bugs are in the transitions, and usually in the transitions of the other thing. Include the rows already in the database, which went through those transitions before the new rules existed and are the least likely to satisfy them.
+
+## What to do with what you find
+
+Not every gap is worth someone's attention. A question earns its place only if a wrong answer changes the code. If the likeliest guess being wrong would cost nothing, take the guess, write it down as an assumption, and move on; a stated assumption gets corrected, a silent one becomes a bug. Thirty questions get ignored, four get answered today.
+
+Ask what survives in the language of whoever wrote the ticket. They know the business and usually not the codebase, so a question they cannot parse earns a guess or a meeting rather than an answer. "Should this column be nullable" is unanswerable by them; "should accounts that never set this keep behaving exactly as they do today" is the same fork in the code, and anyone can answer it. If you cannot restate a question without naming a table, a class or a file, it is usually a decision you should be making yourself, and you are escalating because that feels safer. Make the call and say what it would cost to be wrong.
+
+Give each question its consequence. "What happens to existing subscriptions" gets skimmed. "What happens to the 40k existing subscriptions, because backfilling them as active may bill people who cancelled" gets answered.
+
+## What to produce
+
+A document, written to a file, because this is a loop: answers come back, you run it again, the verdict moves. Keep it in a gitignored scratchpad inside the repository, where it sits beside the code it cites and survives the session without landing in anyone's history. Look at what the repo already ignores before inventing a path, and if nothing fits, exclude it locally rather than editing a tracked ignore file you do not own.
+
+Lead with the verdict and be blunt about it. Ready, needs a spike, or not ready, and why in a sentence. Do not soften it to be encouraging, and be especially careful with the spike case, because a ticket whose questions are all answered can look finished while its riskiest property has never been built here.
+
+Then separate what the business decided from how it resolves in the code, and keep that separation strict. The business half holds the answers only they can give, in language they can confirm or correct, with no table or class or file names anywhere in it. The code half holds your translation, cited, and the author never has to read it. Merged, they skim a paragraph of schema and quietly stop reviewing. Split, each reader gets the half they can judge, and the implementer gets your groundwork instead of redoing it.
+
+Beyond that, shape the document around what you found rather than around a fixed set of headings. A ticket with one blocking question and a clean precedent does not need the same structure as one facing a migration over a table nobody has touched in three years. Say what you checked, including where you looked and found nothing, so a reader can tell the difference between a question you closed and one you never reached.

package/skills/incubator/qrspi-design/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: qrspi-design
+description: Design step of the QRSPI workflow. Interviews the user about the design decisions, with the research facts as evidence, and writes design.md. The design has the current state, the desired end state, the patterns to follow, the decisions and their reasons, what is out of scope, and the open risks. Design is the lowest-cost point to change direction before planning. It reads task.md, research.md, and question-sources.md from the task directory. Use it after qrspi-research-resolve, or when the user says "qrspi design", "/qrspi-design", or "design this from the research".
+---
+
+# QRSPI Design
+
+## Dependencies
+
+- **`simple-english`** (required). Follow it for all text that you write for the user. You can find it in `skills/productivity/` of this repository. If it is not available, stop. Tell the user to install it.
+- **`mattpocock-skills/grilling`** (required). This skill does the interview in step 2. You can find it in the `mattpocock-skills` plugin of Matt Pocock. If it is not available, stop. Tell the user to install it.
+
+This is the design step of QRSPI: Question, Research, Design, Structure, Plan, Test plan, Implement.
+
+In this step you decide where the work goes, before anyone plans how. A change of direction costs the least here. After this step, each change costs more.
+
+You know the goal again. Research found the facts without the goal. Now you weigh these facts against the goal, and the user makes the decisions.
+
+## Input
+
+The user starts the skill like this: `qrspi-design <task-dir>`. For example: `qrspi-design ~/wiki/rate-limit`.
+
+- **`<task-dir>`.** The first argument. This is the directory for all files of this task. If the user does not give it, ask for it.
+- **`<task-dir>/task.md`.** What the user wants.
+- **`<task-dir>/research.md`.** The final research facts from `qrspi-research-resolve`. Each fact has a `file:line` reference or a URL, or a note that the user gave it. The research is done. Do not ask for more research.
+- **`<task-dir>/question-sources.md`.** Why each research question exists. Use it to connect each fact to its concept, its area, and its facet. The facet tells the group of the fact in `design.md`, for example Invariants or Assumptions.
+
+If `research.md` does not exist, stop. Tell the user to run `qrspi-research-resolve` first.
+
+## 1. Read the input
+
+Read all of `task.md`, `research.md`, and `question-sources.md`. Know what the task wants and what exists now before you do more.
+
+Done when you can say in two or three sentences what exists now and what must change.
+
+## 2. Interview the user
+
+Run `grilling`, with these differences:
+
+1. **Evidence.** Base each recommendation on the facts in `research.md`. Give the `file:line` reference or the URL. If a recommendation goes against a fact, say so.
+2. **Existing patterns first.** Recommend a pattern that the code already uses. There are two reasons. The code stays consistent. Also, the team approved these patterns, and they work in production. Look for features with the same shape, not only features with the same name. For example, a register page has the same shape as a contact form: an untrusted user sends a form. Take over what these features do, including their protections, for example rate limits and bot protection. If the work leaves out something that they have, that is a decision. Tell why. Recommend a new pattern only when no existing pattern fits. Then say clearly that it is new, and tell why no existing pattern fits. In `design.md`, each decision shows if it is existing or new.
+3. **Facts.** Do not look up facts yourself, and do not send an agent. If a decision needs a fact that `research.md` does not have, ask the user for it. If the user is not sure, help the user. Tell what the decision loses without the fact. Suggest who can know it, for example a teammate or the owner of the product. Mark each such fact with "(from the user)" in `design.md`.
+4. **Output.** Write `design.md` (step 3).
+
+Where `grilling` and this skill do not agree, this skill wins.
+
+Ask about the decisions that need human judgment, for example:
+
+- Which of the patterns in the code does the work follow? Which patterns must it not follow?
+- Which approach does the work take, when research shows more than one?
+- What must be true when the work is done, and how do we check it?
+- What is out of scope?
+
+For each option, show what it is, where the code already uses it (`file:line`), and its cost.
+
+Done when each decision has an answer from the user.
+
+## 3. Write the design
+
+Write `<task-dir>/design.md`:
+
+```markdown
+# Design
+
+## Current state
+<What exists now, from research.md. Each fact has a file:line reference.
+Put each fact in one group. If a group has no facts, write "None found".>
+
+### How it works
+- A report has the states draft and published. `app/models/report.rb:12`
+
+### Invariants
+<Rules that the code enforces. The work must keep them, or change them on purpose.>
+- A report always has an owner. `app/models/report.rb:14`
+
+### Assumptions
+<What the code takes as true without a check. If the work depends on one, it is a risk.>
+- The code assumes that a member has one account. `app/models/member.rb:8`
+
+### Cascades
+<Changes here that cause changes somewhere else.>
+- Reports are destroyed with the member. `app/models/member.rb:20`
+
+### Who depends on it
+<Callers, consumers of the same data, and owners. When the work changes something, this list shows what else can break.>
+- The dashboard reads the reports table. `app/dashboards/reports_widget.rb:30`
+
+### Lifecycle
+<The states and the moves between them. New code must handle each state.>
+- A report moves from draft to published when the owner shares it. `app/models/report.rb:40`
+
+## Desired end state
+<What we build, and how we check that it is correct.>
+
+## Patterns to follow
+<Code patterns that the work must follow, with file:line references.
+Also the patterns that research found and that the work must not follow, and why.
+Mark each new pattern with "(new)", and tell why no existing pattern fits.>
+
+## Decisions
+<Mark each decision "existing" or "new".
+Existing: the codebase already does this. Give the file:line reference of the place that does it.
+New: the codebase does not do this yet. Tell why no existing way fits.>
+1. **<decision>** (existing): <the choice> - <why>. Done the same way in <file:line>.
+2. **<decision>** (new): <the choice> - <why>. No existing way fits, because <reason>.
+
+## Not doing
+<What is out of scope. This stops the scope from growing in later steps.>
+
+## Open risks
+<What is not certain and can show during the work.>
+```
+
+Keep it short. It is a document that sets the direction. It is not a specification. Structure and Plan add the detail later.
+
+Show `design.md` to the user. Change it until the user approves it.
+
+Done when the user approves the design.
+
+## 4. Hand off
+
+Tell the user: "Next: run `qrspi-structure` with `<task-dir>`."
+
+## Rules
+
+- The user makes the decisions. You recommend, then you wait for the answer.
+- Prefer the patterns that the code already uses. Do not invent a pattern when an existing one fits.
+- Do not write `design.md` before the interview in step 2 is done.
+- Do not research in this step. Research happens only in `qrspi-research`.
+- Each pattern and each current-state fact has a `file:line` reference.
+- Do not plan the work in this step. Do not write file-by-file changes or code. Structure and Plan do that.

package/skills/incubator/qrspi-implement/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: qrspi-implement
+description: Implement step of the QRSPI workflow. Does the work of plan.md one slice at a time. For each slice, it writes the code and the tests. It writes the tests from the test cases of test-plan.md. A slice is done when its checks and its tests pass. After each slice, it ticks the checkboxes in plan.md and makes one commit. The checkboxes show the progress. Thus, a new session can continue where the last one stopped. It reads plan.md and test-plan.md from the task directory. Use it after qrspi-test-plan, or when the user says "qrspi implement", "/qrspi-implement", "implement the plan", or "continue the implementation".
+---
+
+# QRSPI Implement
+
+## Dependencies
+
+- **`simple-english`** (required). Follow it for all text that you write for the user. You can find it in `skills/productivity/` of this repository. If it is not available, stop. Tell the user to install it.
+
+This is the implement step of QRSPI: Question, Research, Design, Structure, Plan, Test plan, Implement.
+
+You do the work of the plan, one slice at a time. `plan.md` tells how to change the code. `test-plan.md` has the black-box test cases. You write the code and the tests. The work is done when each test case of `test-plan.md` has a test, and all tests pass.
+
+The checkboxes in `plan.md` show what is done. If the session stops, the next session reads them and continues.
+
+## Input
+
+The user starts the skill like this: `qrspi-implement <task-dir>`. For example: `qrspi-implement ~/wiki/rate-limit`.
+
+- **`<task-dir>`.** The first argument. This is the directory for all files of this task. If the user does not give it, ask for it.
+- **`<task-dir>/plan.md`.** Your working document for the code.
+- **`<task-dir>/test-plan.md`.** The test cases for each slice. It also lists the expected contract changes.
+
+If `plan.md` does not exist, stop. Tell the user to run `qrspi-plan` first.
+
+If `test-plan.md` does not exist, stop. Tell the user to run `qrspi-test-plan` first.
+
+## 1. Find where to start
+
+Read all of `plan.md` and `test-plan.md`. Find the first slice that has a checkbox that is not ticked (`- [ ]`). Start there.
+
+The ticked checkboxes (`- [x]`) show work that is done. Trust this work, unless something looks wrong.
+
+## 2. Do one slice
+
+1. Read each file that the slice changes, before you change it. Know the code that you change.
+2. Make the changes of the slice. Follow the intent of the plan. If the code is a little different from what the plan expects, adapt to it.
+3. Keep each invariant of the slice, and check each dependent, as the plan tells.
+4. Write a test for the goal case and for each case of the slice in `test-plan.md`. Use the test style of the project. Test only through the interface that each case names. Replace a dependency only where `test-plan.md` tells you to.
+
+You can write the tests first or the code first. You choose the order.
+
+The tests are your work, the same as the code. You can give the tests to a different agent, the tester. In a team, a tester and a developer do this work. Give the tester only `test-plan.md` and the number of the slice. The tester does not need `plan.md`.
+
+Do only the changes of the plan. Do not refactor, clean up, or improve other code, even if that code is not clean. If you see something that must be fixed, tell the user after the slice.
+
+Use sub-agents only for a specific problem, for example to find the cause of an error in code that you do not know.
+
+## 3. Handle a problem in the plan
+
+Sometimes the code is very different from what the plan expects. For example, a dependency is missing, an API is wrong, or the plan has a wrong fact. Then stop, and tell the user:
+
+```
+Problem in slice <N>:
+Expected: <what the plan says>
+Found: <what the code has>
+Effect: <what this means for the plan>
+
+How must I continue?
+```
+
+Write the answer of the user in `plan.md`, in the slice, and mark it with "(from the user)". Then continue.
+
+## 4. Check the slice
+
+1. Run the "By command" checks of the slice. If a check fails, use "Find the cause of a failing test" below. Then run the check again.
+2. When a check passes, tick its checkbox in `plan.md`: `- [ ]` becomes `- [x]`.
+3. Run the tests for the goal case and the cases of the slice.
+
+Done when each "By command" check of the slice passes. The tests for the goal case and the cases of the slice must also pass.
+
+### Find the cause of a failing test
+
+`test-plan.md` lists the expected contract changes for each public interface. Compare each failing test with this list:
+
+- **The failure agrees with a change on the list.** The failure is expected. Change the test to the new contract.
+- **The failure agrees with no change on the list.** The failure is probably a bug. Fix the code. Do not change the test. If you change a test only to make it pass, you hide a broken contract.
+- **You are not sure.** Stop and ask the user.
+- **The code needs a contract change that is not on the list.** Stop and ask the user. The design missed this change.
+
+## 5. Commit the slice
+
+Make one commit for the slice, after its "By command" checks pass. Use a message like "Slice <N>: <name of the slice>". One commit for each slice lets the user undo one slice alone.
+
+## 6. Ask for the checks by hand
+
+Ask the user only when it is necessary. If the slice has no "By hand" checks, go to the next slice.
+
+Otherwise, tell the user:
+
+```
+Slice <N> is done.
+
+Checks by command that passed:
+- [x] <each check>
+
+Please check by hand:
+- [ ] <each check by hand from the plan>
+
+Tell me when this is done. Then I start slice <N+1>.
+```
+
+Tick a "By hand" checkbox only when the user confirms it. If the user told you to do more slices without a stop, continue, and collect the checks by hand for the end.
+
+## 7. Continue
+
+Do steps 2 to 6 for each slice, in the order of the plan.
+
+When all slices are done, tell the user: "Next: run the PR step with `<task-dir>`."
+
+## Rules
+
+- One slice at a time. Do not skip ahead.
+- Read the code before you change it.
+- The checkboxes in `plan.md` are the record of progress. Tick them when a check passes.
+- Tick a "By hand" checkbox only when the user confirms it.
+- A slice is done when its checks pass, and the tests for its goal case and its cases pass.
+- Change an existing test only for a contract change on the list in `test-plan.md`.
+- If the plan is wrong, stop and ask. Do not change the plan in silence.
+- Do only the changes of the plan. Tell the user about other problems after the slice.
+- One commit for each slice, after its checks pass.

package/skills/incubator/qrspi-plan/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: qrspi-plan
+description: Plan step of the QRSPI workflow. Expands each slice of structure.md into exact changes - file paths, what changes in each file, code snippets for the parts that are not obvious, and checks with checkboxes. The plan is the working document of the implementor. An agent that reads only plan.md must be able to do the work. It reads structure.md, design.md, and research.md from the task directory and writes plan.md. Use it after qrspi-structure, or when the user says "qrspi plan", "/qrspi-plan", or "write the implementation plan".
+---
+
+# QRSPI Plan
+
+## Dependencies
+
+- **`simple-english`** (required). Follow it for all text that you write for the user. You can find it in `skills/productivity/` of this repository. If it is not available, stop. Tell the user to install it.
+
+This is the plan step of QRSPI: Question, Research, Design, Structure, Plan, Test plan, Implement.
+
+The plan is the working document of the implementor. It must contain all that the implementor needs, and nothing more. The user approved the design and the structure. The user only checks parts of the plan.
+
+## Input
+
+The user starts the skill like this: `qrspi-plan <task-dir>`. For example: `qrspi-plan ~/wiki/rate-limit`.
+
+- **`<task-dir>`.** The first argument. This is the directory for all files of this task. If the user does not give it, ask for it.
+- **`<task-dir>/structure.md`.** The approved slices.
+- **`<task-dir>/design.md`.** The approved design: current state, patterns, and decisions.
+- **`<task-dir>/research.md`.** The research facts, with `file:line` references.
+
+If `structure.md` does not exist, stop. Tell the user to run `qrspi-structure` first.
+
+## 1. Read the input
+
+Read all of `structure.md`, `design.md`, and `research.md`.
+
+Also read the files that `structure.md` lists, and the files that `design.md` gives as examples of its patterns. You need them to write exact changes. Do not search the code for new facts. Research is done.
+
+Find the commands that the project uses to build, lint, and test. Look in `AGENTS.md`, `CLAUDE.md`, the `Makefile`, `package.json`, or the equivalent files.
+
+## 2. Expand each slice
+
+Do the slices in the order of `structure.md`. Do not change the order. For each slice, write:
+
+- **Changes.** For each file: the exact path, the action (create, change, or delete), and what changes.
+- **Code snippets.** Only for the parts that are not obvious, for example new functions, new types, or migrations. Skip boilerplate. When the change follows an existing pattern, give the `file:line` of the example in the code.
+- **Invariants and dependents.** Take them from the "Touches" list of the slice in `structure.md`. For each invariant, tell how the change keeps it. For each dependent, tell what the implementor must check.
+- **Checks.** The project commands that must pass, and the checks by hand. Each check has a checkbox (`- [ ]`). The implementor uses the checkboxes to track progress.
+
+Put in the plan only the changes of `design.md` and `structure.md`. Do not add refactoring, cleanup, or improvements to other code, even if that code is not clean.
+
+## 3. Check for common gaps
+
+- **Schema migrations.** If a slice changes the schema, also update the tests that check the schema version.
+- **Generated code.** If a slice needs code generation, tell what to do when the generator fails or is not available. For example, add the fields by hand to the generated files.
+- **Coverage.** Each file in `structure.md` is in the plan.
+
+## 4. Handle an open question
+
+The plan must not have open questions. If you find one, stop. Ask the user. Write the answer in the plan, and mark it with "(from the user)".
+
+Sometimes a slice cannot be done as `structure.md` says, for example because a file is different from the structure. Do not work around it without a word. Tell the user what you found, and ask how to resolve it. Write the answer in the plan, and mark it with "(from the user)".
+
+## 5. Write the plan
+
+Write `<task-dir>/plan.md`:
+
+````markdown
+# Plan
+
+## Overview
+<1-2 sentences, from the desired end state in design.md.>
+
+## Slice 1: <name from structure.md>
+
+### Changes
+
+#### 1. <file or group of files>
+**File**: `path/to/file.ext`
+**Action**: <create / change / delete>
+<What changes. Follow the pattern in `path/to/example.ext:40`.>
+
+```language
+// the code to add or change, only where it is not obvious
+```
+
+#### 2. <next file>
+...
+
+### Invariants and dependents
+- Invariant: <the invariant> - <how the change keeps it>
+- Dependent: <the dependent> - <what to check>
+
+### Checks
+#### By command
+- [ ] <project lint or test command> passes
+- [ ] <a command for this slice>
+
+#### By hand
+- [ ] <what to check, and the expected result>
+
+## Slice 2: <name>
+...
+````
+
+## 6. Show the summary
+
+Give the user a short summary of the plan. Tell each place where the plan does not follow `structure.md`, and why.
+
+Tell the user: "Next: run `qrspi-test-plan` with `<task-dir>`."
+
+## Rules
+
+- The plan is complete. An agent that reads only `plan.md` can do the work.
+- Follow the slice order of `structure.md`.
+- Follow the existing patterns. Give the `file:line` of the example for each pattern.
+- Each check has a checkbox.
+- The plan has no open questions.
+- Use the commands of the project for the checks.

package/skills/incubator/qrspi-question/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: qrspi-question
+description: First step of the QRSPI workflow. Turns a task into neutral research questions with the clean room method. You know the goal. The researcher must not know it. questions.md is the only thing that crosses the wall. The skill finds the areas of the code that the task affects. It asks a fixed set of facets for each area. It tests the questions for goal leaks. It reads task.md from the task directory and writes questions.md for the qrspi-research step. Use it to start a QRSPI run, or when the user says "qrspi", "start qrspi", "qrspi question", "/qrspi-question", "make the research questions", or "turn this task into research questions".
+---
+
+# QRSPI Question
+
+## Dependencies
+
+- **`simple-english`** (required). Follow it for all text that you write for the user. You can find it in `skills/productivity/` of this repository. If it is not available, stop. Tell the user to install it.
+- **`codebase-locator`** (required). This agent does the scan in step 2. You can find it in the `agents/` directory of this repository. If it is not available, stop. Tell the user to install it.
+
+This is the first step of QRSPI: Question, Research, Design, Structure, Plan, Test plan, Implement.
+
+## The clean room
+
+This step uses the clean room method. Companies used this method to copy a product legally. A dirty team studies the original product and writes a spec. A clean team never sees the original product. The clean team builds only from the spec. A reviewer makes sure that the spec contains nothing from the original product.
+
+In QRSPI:
+
+| Clean room | QRSPI |
+|---|---|
+| Dirty team | You. You know the goal. |
+| The spec | `questions.md`. It is the only thing that crosses the wall. |
+| The reviewer | The leak test. |
+| Clean team | The researcher. It never sees the goal. |
+
+Why: a researcher who knows the goal finds the facts that support the goal. That researcher misses the other facts. A researcher who does not know the goal cannot bend the facts. You must know the goal. Only the goal tells you which facts are necessary.
+
+## Input
+
+The user starts the skill like this: `qrspi-question <task-dir>`. For example: `qrspi-question ~/wiki/rate-limit`.
+
+- **`<task-dir>`.** The first argument. This is the directory for all files of this task. If the user does not give it, ask for it.
+- **`<task-dir>/task.md`.** This file tells what the user wants. It can have any form: a few lines, a ticket, or a link to an issue. If it does not exist, tell the user to write it. Do not change it.
+
+## 1. Find the concepts
+
+Make a list of the concepts that the task names or needs. For example, take the task "rate limit the public API per plan". Its concepts are: public API requests, client identity, plans, shared storage, and how other systems limit rates.
+
+A concept does not stand alone. It connects to other things in many ways. For example:
+
+- **Lifecycle.** It changes state over time.
+- **Ownership.** Other records own it or depend on it. For example, a saved report belongs to a member. When the member is suspended or deleted, something happens to the report.
+- **Producer and consumer.** It writes data that other code reads, or it reads data that other code writes. For example, the new feature writes to the table of concept A. Concept B reads that table, but no code in A calls B.
+- **Cascade.** A change to it causes a change somewhere else. For example, a foreign key with `ON DELETE CASCADE` deletes the rows of B when a row of A is deleted. Triggers, callbacks, and events can also cause cascades.
+
+Some connections, for example producers, consumers, and cascades, are frequently not in the calls between the code. Thus a search that follows calls does not find them. Step 2 finds their code, and step 3 asks about the connections.
+
+Also name the shape of the work. The shape is the kind of work, without the name of the feature. For example, a register page and a contact form have the same shape: an untrusted user sends a form. Features with the same shape have the same needs, for example input checks, rate limits, and bot protection. Step 2 finds the features that have the same shape.
+
+If the task is too vague for this list, stop. Ask the user to make the task clearer. Do not guess.
+
+Done when each concept is a short noun phrase.
+
+## 2. Find the affected areas
+
+For each concept, find its location in the code. Use `codebase-locator`. Get only paths and names. Do not read the code to learn how it works. That work is research.
+
+Each location that you find is an affected area. In this skill, "area" always means an affected area. Some concepts are not in the code, for example how other systems do something. Such a concept is a web area.
+
+Then find the blind spots: related areas that no concept names. Use `codebase-locator` to search for:
+
+- **Neighbors.** Code next to each area.
+- **Same shape.** Other features with the same shape as the work, for example the contact form for a register page.
+- **Producers and consumers.** Code that uses the names of the data stores of each area. Data stores are, for example, tables, columns, files, caches, or queues.
+- **Cascades.** Foreign keys, triggers, callbacks, and event handlers that use the names of these data stores. Look in the schema, the migrations, and the model definitions.
+
+Add each blind spot as an area. Mark it as a blind spot.
+
+Done when each concept has one or more areas.
+
+## 3. Ask the facets for each area
+
+For each area, write the questions from this checklist. Do not ask only the questions that the goal makes you think of.
+
+For a code area:
+
+| Facet | Question shape |
+|---|---|
+| Flow | How does control get to it? Where does control go next? |
+| Contracts | What calls it? What does it call? |
+| Data | Which data does it read or write? Where does it keep the data? |
+| Data relationships | How does its data relate to other data? For example: foreign keys, associations, join tables, or copies of the same data in other places. |
+| Producers and consumers | Which other code writes the data that it reads? Which other code reads the data that it writes? |
+| Lifecycle | Which states can it have? What moves it from one state to the next state? What runs at each change, for example callbacks, jobs, events, or emails? |
+| Ownership | Which records own it? Which records depend on it? What happens to it when these records change state? For example, the records are suspended, deleted, merged, or moved to another plan. |
+| Cascades | What else changes when it changes or is deleted? For example: database cascades, triggers, callbacks, or events. |
+| Invariants | What must always be true here? Which code makes sure of it? For example: soft delete, audit trails, or records that must not change. |
+| Config | Which settings or environment values change what it does? |
+| Limits | Which limits apply? For example: sizes, rates, timeouts, or dependencies on other services. |
+| Assumptions | What does the code accept as true without a check? For example: state, users, or input. |
+| Errors | What happens when it fails? What happens at the edge cases? |
+| Tests | Which tests check it now? |
+| Precedent | Which other features have the same shape? How did the team build them? Which protections and checks do they have? |
+
+For a web area:
+
+| Facet | Question shape |
+|---|---|
+| Options | Which approaches or tools exist? |
+| Trade-offs | What do their docs say about the costs and limits of each option? |
+| Standards | Which specs or standards apply? |
+| Use | Which known systems use which option? |
+
+Skip a facet only when it clearly does not apply to the area. All facets are necessary for two reasons:
+
+- You get the facts that the goal did not make you think of.
+- Each area gets the same facets. Thus the researcher cannot see which facet is important to you.
+
+Done when each area has a question for each facet that applies.
+
+## 4. Merge and split
+
+- **Merge** two questions when they send the researcher to the same code.
+- **Split** a question when it asks about two things that are not related.
+
+Do not merge or split to get a specific number. The number of questions is a result, not a target.
+
+Done when no two questions overlap and each question asks about one thing.
+
+## 5. Write each question neutrally
+
+- **Describe. Do not propose.** "How does X work?" is correct. "How should we change X?" is not correct.
+- **Ask about all the options.** "What shared storage does the app use?" is correct. "Can we use Redis?" is not correct.
+- **Do not put an assumed fact in the question.** "Where does the app check API keys?" assumes that the app checks API keys. "How does the app find out who sent a request?" does not assume this.
+- **Trace a flow.** Do not ask a yes-or-no question.
+
+Put one tag at the start of each question: `[code]` or `[web]`.
+
+## 6. Test for leaks
+
+This test is the reviewer of the clean room. Nothing from the goal can cross the wall.
+
+1. Read only `questions.md`, as the researcher will read it. Find the words that show what we will build or change. Write these words again.
+2. If you can start a sub-agent, give it only `questions.md`. Ask it to guess the task. The sub-agent does not know the goal, thus this test is stronger. If its guess is close, find the words that told it. Then write the questions again.
+
+Done when the questions do not show what we will build.
+
+## 7. Check the size
+
+- **More than approximately 10 areas.** Tell the user. The task can be too large. Offer to split it.
+- **Only one area.** Tell the user. QRSPI can be too much for this task.
+
+## 8. Write the files
+
+Write `<task-dir>/questions.md`. This file is the spec. It crosses the wall:
+
+```markdown
+# Research questions
+
+## Context
+<1-2 sentences: the areas to look at. Name areas only. "The request pipeline and shared storage" is correct. "Areas related to request throttling" is not correct.>
+
+## Questions
+1. [code] <question>
+2. [web] <question>
+```
+
+Write `<task-dir>/question-sources.md`. This file stays on your side of the wall. Design reads it to know why each question exists:
+
+```markdown
+# Question sources
+
+| Q | Concept | Area | Facet | From |
+|---|---------|------|-------|------|
+| Q1 | client identity | app/middleware/ | Flow | concept |
+| Q2 | shared storage | config/ | Data | concept |
+| Q3 | request logging | app/logging/ | Contracts | blind spot |
+```
+
+Show the user `questions.md` and the sources table. The table shows why the number of questions is what it is. Wait for approval.
+
+Done when the user approves the questions.
+
+## 9. Hand off
+
+Tell the user: "Next: run `qrspi-research` with `<task-dir>`."
+
+# Rules
+
+- Research reads only `questions.md`. Never give research `task.md` or `question-sources.md`.
+- Do not change `questions.md` after approval.
+- Sometimes you cannot ask a question without showing the goal. Then tell the user. Do not hide the problem with a vague question.