@ervis/skills 0.1.0

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

@@ -0,0 +1,109 @@
+---
+name: qrspi-research
+description: Second step of the QRSPI workflow. Answers the research questions in questions.md with facts only. Each fact has a file:line reference or a URL. The answers contain no opinions. The researcher does not know what the team will build. The skill reads questions.md from the task directory and writes the answers to research-draft.md. The qrspi-research-resolve step then settles the gaps and writes the final research.md. Use it after qrspi-question, or when the user says "qrspi research", "/qrspi-research", or "research the questions".
+---
+
+# QRSPI Research
+
+## 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`**, **`codebase-analyzer`**, **`codebase-pattern-finder`** (required). These agents answer the `[code]` questions in step 2. You can find them in the `agents/` directory of this repository. If one of them is not available, stop. Tell the user to install it.
+- **`web-search-researcher`** (required). This agent answers the `[web]` questions 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 second step of QRSPI: Question, Research, Design, Structure, Plan, Test plan, Implement.
+
+You only describe what exists. You answer the research questions with facts, code references, and the patterns that you see. You do not know what the team will build. You do not propose solutions.
+
+Why: a researcher who knows the goal finds the facts that support the goal. That researcher misses the other facts. The `qrspi-question` step wrote the questions so that they do not show the goal. Keep the goal hidden.
+
+## Input
+
+The user starts the skill like this: `qrspi-research <task-dir>`. For example: `qrspi-research ~/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>/questions.md`.** This file is your only input.
+
+Do not read `task.md`, `question-sources.md`, or other files in `<task-dir>`. Do not ask the user what the team will build.
+
+Run this skill in a new session. If the session already knows the task, the research is not blind.
+
+## 1. Read the questions
+
+Read all of `questions.md`.
+
+## 2. Send the questions to agents
+
+Send the questions to agents. Start the agents at the same time:
+
+- **`[code]` questions:**
+  - `codebase-locator` finds the locations of the files and components.
+  - `codebase-analyzer` traces how the code works. It gives `file:line` references.
+  - `codebase-pattern-finder` finds examples of the patterns in the question.
+- **`[web]` questions:** `web-search-researcher` finds docs, specs, and other sources. It gives URLs.
+
+Give one or two questions to each agent. Give the agent only the text of these questions. Do not give it other files or this conversation. Tell each agent: "Describe what exists. Do not suggest changes or solutions."
+
+Wait until all agents are done.
+
+## 3. Put the findings together
+
+Connect the findings across the components. If two agents do not agree, read the code yourself. Find which agent is correct.
+
+Done when each question has an answer or a clear "could not answer".
+
+## 4. Write the findings
+
+Write `<task-dir>/research-draft.md`.
+
+```markdown
+# Research draft
+
+## Q1: <question text>
+
+### Findings
+- <fact, with `file:line` or URL>
+- <how the components connect>
+- <patterns that you see>
+
+### Also found
+- <a related fact that the question did not ask for, with `file:line` or URL>
+
+## Q2: <question text>
+...
+
+## Across the questions
+<patterns, conventions, or architecture that two or more questions touch>
+
+## Open
+<each question that you could not answer fully, and why>
+```
+
+Keep it short. Use `file:line` references, not long explanations.
+
+## 5. Show the summary
+
+Give the user a short summary. Then ask:
+
+```
+1. Add a question that is missing.
+2. Continue to `qrspi-research-resolve`.
+```
+
+If the user chooses 1:
+
+1. Add the question to `questions.md`. Give it the next number. Put the tag `[user]` next to its `[code]` or `[web]` tag.
+2. Research it as in steps 2 and 3.
+3. Add the answer to `research-draft.md`.
+4. Ask the two options again.
+
+If the user chooses 2, tell the user: "Next: run `qrspi-research-resolve` with `<task-dir>`."
+
+## Rules
+
+- You describe. You do not criticize. Describe what is, not what should be.
+- Do not suggest improvements, refactoring, or solutions.
+- Each finding has a `file:line` reference or a URL.
+- If you cannot answer a question, say so clearly. Do not guess.
+- "Also found" contains only facts. It does not contain opinions or ideas for changes.
+- If a question is too vague or looks at the wrong area, answer what you can. Write the problem under "Open". `qrspi-research-resolve` settles it with the user.

package/skills/incubator/qrspi-research-resolve/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: qrspi-research-resolve
+description: Step of the QRSPI workflow between research and design. Grades each research answer in research-draft.md. If some answers are weak, contradictory, or open, it interviews the user, who answers or skips each one. If no answer has a gap, it does not interrupt the user. It then writes the final research.md for the design step. After this step, the research is done. Use it after qrspi-research, or when the user says "qrspi research resolve", "/qrspi-research-resolve", "resolve the research", or "settle the research gaps".
+---
+
+# QRSPI Research Resolve
+
+## 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 step is between research and design in QRSPI: Question, Research, Design, Structure, Plan, Test plan, Implement.
+
+Research writes its answers blind to `research-draft.md`. Some answers are strong. Others are weak, do not agree, or are missing. In this step you find these gaps. The user answers or skips each gap. Then you write `research.md`, the final facts that design uses. After this step, the research is done. There are no more research questions.
+
+You know the goal. Only the goal tells you which answers are strong enough for the task. Thus the grading happens here, on the side of the wall that knows the goal.
+
+## Input
+
+The user starts the skill like this: `qrspi-research-resolve <task-dir>`. For example: `qrspi-research-resolve ~/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>/questions.md`.** The research questions.
+- **`<task-dir>/question-sources.md`.** Why each question exists.
+- **`<task-dir>/research-draft.md`.** The answers from `qrspi-research`.
+
+If `research-draft.md` does not exist, stop. Tell the user to run `qrspi-research` first.
+
+## 1. Grade each answer
+
+Read all input files. Give one grade to each answer:
+
+- **Strong.** It has `file:line` or URL evidence. The evidence proves the claim. It does not only mention the claim.
+- **Weak.** It is thin, only inferred, or has only one source.
+- **Contradictory.** It does not agree with another answer.
+- **Open.** The researcher could not answer it.
+
+An answer is strong enough when the task can use it to decide how to build. An answer that the task does not need has no gap, whatever its grade.
+
+The tag `[user]` shows a question that the user added during research. Such a question did not go through the leak test. If its words showed the goal, its answer can lean toward the goal. Grade it with more care.
+
+Also read the "Also found" items. An item is important if the task or an invariant can depend on it. Treat each important item as an open answer.
+
+Done when each answer and each important item has a grade.
+
+## 2. Interview the user
+
+Ask the user only when it is necessary. If no answer is weak, contradictory, or open, and no important "Also found" item exists, do not interview the user. Go to step 3.
+
+Otherwise, run `grilling` on these items: each weak, contradictory, or open answer, and each important "Also found" item. For each item, show what research found, with its `file:line` references or URLs. Then the user resolves the item in one of two ways:
+
+1. **Answer.** The user gives the correct fact.
+2. **Skip.** The user decides that the task does not need this fact.
+
+Recommend one of the two, and tell why. Sometimes the user is not sure. Then help the user decide. Tell what the task loses without the fact. Suggest who can know it, for example a teammate or the owner of the product. Each item must end with an answer or a skip, because design needs a clear set of facts.
+
+Do not look up facts yourself, and do not send an agent. The user resolves the items. Where `grilling` and this skill do not agree, this skill wins.
+
+Done when each item has an answer or a skip.
+
+## 3. Write the final research
+
+Write `<task-dir>/research.md`. Take the facts from `research-draft.md` and from the user. Do not change `research-draft.md`.
+
+```markdown
+# Research
+
+## Q1: <question text>
+- <fact, with `file:line` or URL>
+- <fact from the user> (from the user)
+
+## Q2: <question text>
+...
+
+## Also found
+- <important related fact, with `file:line` or URL>
+```
+
+Keep only facts that the evidence proves or that the user gave. Mark each fact that the user gave with "(from the user)". Do not include the items that the user skipped.
+
+Tell the user:
+
+- The number of gaps, and how the user resolved each one.
+
+Tell the user: "Next: run `qrspi-design` with `<task-dir>`."
+
+## Rules
+
+- Do not research in this step. The user resolves the gaps.
+- After this step, the research is done. Do not send new questions to research.
+- Never give research `task.md`, `question-sources.md`, or `research.md`.
+- The user resolves each gap with an answer or a skip. You recommend, then you wait for the user.

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

@@ -0,0 +1,116 @@
+---
+name: qrspi-structure
+description: Structure step of the QRSPI workflow. Breaks the approved design into vertical slices, where each slice works end to end and has a check. For each slice, it lists the files, the key signatures and types, and the invariants and dependents that it touches. It reads design.md and research.md from the task directory and writes structure.md for the plan step. Use it after qrspi-design, or when the user says "qrspi structure", "/qrspi-structure", or "break the design into slices".
+---
+
+# QRSPI Structure
+
+## 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 structure step of QRSPI: Question, Research, Design, Structure, Plan, Test plan, Implement.
+
+The design tells where the work goes. In this step you tell how the work gets there, in slices. Each slice works end to end and has a check. You show the signatures, the types, and the slice boundaries. You do not write the implementation. Plan adds that detail.
+
+## Input
+
+The user starts the skill like this: `qrspi-structure <task-dir>`. For example: `qrspi-structure ~/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>/design.md`.** The approved design.
+- **`<task-dir>/research.md`.** The research facts, with `file:line` references.
+
+If `design.md` does not exist, stop. Tell the user to run `qrspi-design` first.
+
+## 1. Read the input
+
+Read all of `design.md` and `research.md`.
+
+Done when you know each decision in the design, and the invariants and dependents in its current state.
+
+## 2. Make vertical slices
+
+Break the work into vertical slices. Each slice delivers one piece of the work end to end:
+
+- It goes through all layers that it needs, for example database, service, API, and UI.
+- You can check it alone, after it is done.
+- It has a clear check.
+
+**Vertical** (correct):
+
+> Slice 1: Add the "reticulate" endpoint: migration, store method, API handler, and a basic UI button. Check: the endpoint returns 200, and the button calls it.
+
+**Horizontal** (not correct):
+
+> Slice 1: All database migrations. Slice 2: All service methods. Slice 3: All API endpoints. Slice 4: All UI changes.
+
+Follow the patterns and the decisions in `design.md`. Use the names, signatures, and file locations that the existing code uses. Do not make a new structure when the code already has one.
+
+If a part of the design cannot be sliced vertically, say so in `structure.md`.
+
+## 3. Put the slices in order
+
+Put the slices that others build on first. If a later slice fails, the earlier slices must still have value alone.
+
+## 4. Describe each slice
+
+For each slice, write:
+
+- **Delivers.** What it does end to end, in one or two sentences.
+- **Files.** Each file that it creates or changes.
+- **Key changes.** New or changed signatures and types. Signatures only, not the code.
+- **Touches.** The invariants, cascades, and dependents from the current state of `design.md` that this slice touches. The implementor must keep each invariant, and must check each dependent.
+- **Check.** How to see that the slice works: a command, and what to look at by hand.
+
+## 5. Handle a problem in the design
+
+Sometimes you find that the design missed a constraint or used a wrong fact. Do not work around it without a word. Tell the user what you found. Ask the user how to resolve it. Write the answer in `structure.md`, and mark it with "(from the user)".
+
+## 6. Write the structure
+
+Write `<task-dir>/structure.md`:
+
+```markdown
+# Structure
+
+## Approach
+<1-2 sentences: the approach of design.md, in short.>
+
+## Slice 1: <name>
+<What this slice delivers end to end.>
+
+**Files**: `path/to/file.ext`, `path/to/other.ext`
+**Key changes**:
+- `functionName(param: Type): ReturnType` - new or changed
+- `NewType { field: Type }` - new type
+**Touches**:
+- Invariant: <the invariant> - keep it.
+- Dependent: <the dependent> - check it.
+**Check**: <command>; <what to look at by hand>
+
+## Slice 2: <name>
+...
+
+## Checkpoints
+<What must be true after each slice. This helps to continue after a break.>
+```
+
+Keep it short. Show what changes, not how. If it gets long, you are writing the plan.
+
+Show `structure.md` to the user. The user can change the order of the slices, split a slice, or ask for more detail. Change it until the user approves it.
+
+Done when the user approves the structure.
+
+## 7. Hand off
+
+Tell the user: "Next: run `qrspi-plan` with `<task-dir>`."
+
+## Rules
+
+- Vertical slices, not horizontal layers. Each slice goes through all the layers that it needs.
+- Signatures and types, not the implementation.
+- Each slice has a check.
+- Each slice lists the invariants and dependents that it touches.
+- Follow the patterns and decisions of `design.md`. Do not add decisions that the design did not make.
+- Do not research in this step. If a fact is missing, ask the user, as in step 5.

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

@@ -0,0 +1,253 @@
+---
+name: qrspi-test-plan
+description: Test plan step of the QRSPI workflow. Writes the black-box test cases for each slice of structure.md, in plain words. Each slice gets one goal case. Each public interface gets a case for each rule, in Given / When / Then. The cases guard the scope and the design, so the agent can change the inner code freely. The implement step writes the code and the tests from them. It reads structure.md, design.md, and research.md from the task directory. It does not read plan.md. It writes test-plan.md. Use it after qrspi-plan, or when the user says "qrspi test plan", "/qrspi-test-plan", "write the test plan", "write the test cases", or "plan the tests".
+---
+
+# QRSPI Test 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 test plan step of QRSPI: Question, Research, Design, Structure, Plan, Test plan, Implement.
+
+The test plan is a contract. Its test cases record the scope and the design. The implement step writes the code and the tests. When the code changes, the tests show if the scope or the design broke.
+
+An agent can rewrite inner code quickly and at low cost. Thus, the plan has only black-box test cases for public interfaces. It has no test cases for inner code. The implement step decides about tests for inner code.
+
+The test cases also teach. A reader of the test cases must learn what the feature does. A reader must also learn how to use each public interface.
+
+## Input
+
+The user starts the skill like this: `qrspi-test-plan <task-dir>`. For example: `qrspi-test-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.
+
+Do not read `plan.md`, even if it exists. The plan tells how the code works. A test case from the plan checks how the code works. It also copies the mistakes of the plan. A test case from the design and the slices checks what must be true. Thus, it is an independent check of the code.
+
+## 1. Read the input
+
+Read all of `structure.md`, `design.md`, and `research.md`.
+
+Do not search the code for new facts. Research is done.
+
+Done when you know each slice and each design decision. You must also know the clients of the code that the work changes.
+
+## 2. Find the public interfaces
+
+A public interface is a contract with a client. A client is a person, a system, or code that uses the interface:
+
+- An end user or an outside system. It uses HTTP, a UI, a job, or a CLI.
+- A different module. It imports our classes or our methods. We cannot change this API without care.
+- A future client. `design.md` makes the interface for clients on purpose.
+
+The contract has two parts. Write test cases for the two parts.
+
+- **Behavior.** What the interface does. For example: rules, errors, and side effects such as an email.
+- **Data.** What the interface gives to clients or keeps for clients. For example: response fields, arguments, return values, event payloads, tables that a different module reads, and email content.
+
+Code without a client is inner code. Do not write test cases for it. The agent can change it freely.
+
+For each public interface, write this data:
+
+- **Level.** Write `top` for the outermost entry point of a feature. Write `interface` for a public interface below it.
+- **Clients.** Write each client of the interface. Get them from `research.md` and `design.md`.
+- **Contract.** Write its behavior and its data in plain words.
+- **Expected contract change.** Write the change that `design.md` makes on purpose. For a new interface, write "none". For a change to inner code only, write "none". Step 6 tells more.
+
+Done when each public interface of the slices has a level, clients, a contract, and an expected change.
+
+## 3. Find the outermost layer of each slice
+
+The size of the box is different for each request. For each slice, find the outermost layer that the change touches. That layer is the box.
+
+A black-box test case has two sides. The two sides must be on the outermost layer.
+
+- **Input side.** This is where the actor starts the action. For example, a user shares a report with `POST /reports/:id/shares`. The user does not call a mailer.
+- **Output side.** This is where a person outside the system sees the result. For example, the email that the member gets. "The mailer was called" is not an output. "A job is in the queue" is not an output. These are inner parts.
+
+Some changes touch only a job. Then the job is the box. Some changes touch only a method that a different module calls. Then that method is the box.
+
+## 4. Write the test cases
+
+Put the test cases on two levels:
+
+- **Top level.** Write one goal case for each slice. The slice is done when the test for its goal case passes. Also write the cases that show the connections. For example: "A rule fails. The response is 422."
+- **Interface level.** Write all other cases here. Put each rule on the lowest public interface. There, tests are fast and exact.
+
+Each test case is a black-box case for its own interface.
+
+Write a case for each rule and each decision of a slice. For each public interface, look for these cases:
+
+- the usual path
+- each rule that fails
+- each limit value
+- a duplicate action
+- each permission
+- empty input
+- each change of state
+- each data field of the contract
+
+Each case has these parts:
+
+- **Name.** Use words of the business domain. The name tells the intent. For example: "A non-owner cannot share".
+- **Interface.** Write the interface and its level.
+- **Guards.** Write the rule or the decision that the case guards. Copy its text from `design.md` or `structure.md`.
+- **Given / When / Then.** Write **Then** as a list of exact checks. Each check must be visible on the output side of the box. Logs and calls to inner parts are not outputs.
+
+Write the top level as business rules. Use words of the business domain. A person who does not write code must understand it.
+
+Write the interface level as examples of use for a developer of a client module. Tell what to call, what to send, and what comes back.
+
+Write the test cases in plain words. Do not write test code. The implement step writes the tests.
+
+## 5. Make the test cases repeatable
+
+A test must give the same result each time.
+
+Each **Given** makes only the data for its case:
+
+- Cases do not share setup.
+- The order of the cases is not important.
+- The database is clean at the start of each case.
+
+A small **Given** also teaches. Each line of setup shows a fact that is important for the rule.
+
+A real database is correct in tests.
+
+Some values change from one run to the next. Write each source of change, and tell how the tests must control it:
+
+- **Time.** A rule can use the time. Then the **Given** sets a fixed date.
+- **Background jobs.** The test runs the jobs. Then it checks the result on the output side.
+- **Generated values.** For example: IDs, tokens, and the order of results. Do not check them. Check them only if they are part of the contract.
+- **Outside services.** Use the rules for replacements below.
+- **Two actions at the same time.** Tell if this is in scope. If it is in scope, tell how to test it. If it is not in scope, write it in **Known gaps**.
+
+Do not use mocks, if possible. Use the real code in the box. With a mock, a test can pass when the real code fails.
+
+Replace a dependency only for one of these reasons:
+
+- We cannot control its behavior. For example, an outside HTTP service.
+- A real dependency is too slow or too expensive for a test.
+
+Replace a dependency only on the outer edge of the system. Do not replace a part in the box.
+
+Each replacement must have a contract test, if possible. A contract test makes sure that the replacement and the real service agree. For example:
+
+- The test runs the same checks on the test system of the real service.
+- The test is a contract that the client writes, for example with Pact.
+
+A contract test is not always possible. Then tell why. Also tell the source of truth for the replacement. For example: the API documents, or a recorded real response.
+
+## 6. Write the expected contract changes
+
+Some work changes a contract on purpose. Then some existing tests must fail. The implement step must know which failures are expected. All other failures are probably bugs.
+
+For each public interface, get the planned change from `design.md`. Write two things in plain words:
+
+- what changes
+- which existing tests can fail because of it
+
+For a change to inner code only, write "none". Then no existing test can fail.
+
+Do not search the code for the existing tests. The implement step compares each real failure with this list.
+
+## 7. Record a problem in the previous steps
+
+Exact checks can show a problem that the previous steps did not find. For example:
+
+- The design does not tell what occurs in a case.
+- A slice has no clear goal case.
+- A case cannot pass with the design as it is.
+
+If you find a problem, stop. Do not solve it. Do not change `design.md` or `structure.md`.
+
+Write the problem in the **Findings** section of `test-plan.md`:
+
+- what you found
+- the case that shows it
+- the file that it affects: `design.md` or `structure.md`
+
+Tell the user about the problem. The user solves it and updates the previous steps. Then the user starts this skill again.
+
+## 8. Write the test plan
+
+Write `<task-dir>/test-plan.md`.
+
+The file must be complete alone. The implement step must be able to write all the tests from this file only. Thus, copy the rule text and the contracts into the file. Do not refer to other files for them.
+
+For a full example, read `references/example-test-plan.md`.
+
+````markdown
+# Test plan
+
+## Approach
+<1-2 sentences: what the work gives, from design.md.>
+
+## Public interfaces
+
+### <interface, for example POST /reports/:id/shares>
+**Level**: top | interface
+**Clients**: <who uses it>
+**Contract**: <behavior and data, in plain words>
+**Expected contract change**: <what changes on purpose, and which existing tests can fail> | none
+
+## Outside dependencies
+| Dependency | How tests control it | Contract test or source of truth |
+|---|---|---|
+| <dependency> | <real, or replaced on the edge> | <contract test, or source and reason> |
+
+## Known gaps
+<What the test cases do not cover, and why. "None" if there are no gaps.>
+
+## Slice 1: <name from structure.md>
+<What the slice gives, copied from structure.md.>
+
+### Goal case
+**Interface**: <interface> (top)
+**Given** <the state before the action>
+**When** <the action>
+**Then**:
+- <exact check>
+
+### Cases
+#### TC-1.1 <intent, in words of the business domain>
+**Interface**: <interface> (<level>)
+**Guards**: "<rule or decision, copied>"
+**Given** ...
+**When** ...
+**Then**:
+- <exact check>
+
+## Slice 2: <name>
+...
+
+## Findings
+<Problems for the user to solve in the previous steps. "None" if there are no problems.>
+````
+
+Show `test-plan.md` to the user. The user can add, change, or remove cases. Change the file until the user approves it.
+
+Done when the user approves the test plan and **Findings** is "None".
+
+## 9. Hand off
+
+Tell the user: "Next: run `qrspi-implement` with `<task-dir>`."
+
+## Rules
+
+- Write only black-box test cases for public interfaces. Do not write test cases for inner code.
+- Do not read `plan.md`.
+- Write one goal case for each slice, on the top level.
+- Put the cases for each rule on the lowest public interface.
+- Each case guards a rule or a decision. Copy its text.
+- Write **Then** as a list of exact checks on the output side of the box.
+- Do not use mocks, if possible. Replace only on the outer edge. Use a contract test, if possible.
+- Make `test-plan.md` complete alone.
+- Write test cases, not tests. The implement step writes the code and the tests.
+- Do not do research. Do not change the previous files. Write a problem in **Findings**, and stop.