@ervis/skills 0.1.0

package/skills/incubator/qrspi-test-plan/references/example-test-plan.md

@@ -0,0 +1,151 @@
+# Example test plan
+
+This is a full `test-plan.md` for a small feature. The owner of a report shares it with members of the same workspace.
+
+Look at these parts:
+
+- `Report#viewable_by?` has an expected contract change. It tells the implement step which failures of old tests are expected.
+- **Clients** shows why `Report#share_with` is public. The Slack module imports it.
+- The cases for the rules are on the `interface` level. The `top` level has only the goal cases and the HTTP responses (TC-1.5).
+- Each case copies the rule that it guards. Thus, the implement step can write the tests from this file only.
+
+````markdown
+# Test plan
+
+## Approach
+The owner of a report shares it with members of the same workspace.
+All sharing rules live in `Report#share_with`. The controller only
+maps its result to HTTP. The member gets an email.
+
+## Public interfaces
+
+### POST /reports/:id/shares
+**Level**: top
+**Clients**: web app, mobile app
+**Contract**: The owner sends a member id. Response 201 with
+`{ member_id, report_id, shared_at }` for a new share, 200 with the
+same body for an existing share, 403 if not the owner, 422 with
+`{ error }` if a rule fails.
+**Expected contract change**: none (new endpoint)
+
+### Report#share_with(member, by:)
+**Level**: interface
+**Clients**: the shares controller, the Slack module (imports it to
+share from Slack)
+**Contract**: Returns `:created` or `:already_shared`. Raises
+`Report::NotAllowed` if `by` is not the owner. Raises
+`Report::InvalidMember` if the member is not in the workspace. Sends
+one email for `:created` only.
+**Expected contract change**: none (new method)
+
+### Report#viewable_by?(user)
+**Level**: interface
+**Clients**: the reports controller, the search module
+**Contract**: True for the owner and for workspace admins.
+**Expected contract change**: also true for shared members. Existing
+tests that expect `false` for a non-owner member can fail if that
+member now has a share. Any other failure is a probable bug.
+
+## Outside dependencies
+| Dependency | How tests control it | Contract test or source of truth |
+|---|---|---|
+| Database | real, clean for each case | - |
+| Email | background job runs in the test; check the test mail box | Rails mail delivery, no fake |
+
+## Known gaps
+- Two shares of the same report at the same moment. Not in scope: the
+  design accepts the rare duplicate email.
+
+## Slice 1: Share a report and view it
+The owner shares a report with a workspace member. The member can
+view it, but cannot edit it.
+
+### Goal case
+**Interface**: POST /reports/:id/shares (top)
+**Given** Alice owns report R. Bob is in her workspace.
+**When** Alice posts to `/reports/R/shares` with Bob.
+**Then**:
+- the status is 201
+- the body has Bob's id and R's id
+- Bob's `GET /reports/R` returns 200
+
+### Cases
+#### TC-1.1 A non-owner cannot share
+**Interface**: Report#share_with (interface)
+**Guards**: "Only the owner can share the report."
+**Given** Alice owns R. Carol is in the workspace.
+**When** Carol shares R with Bob.
+**Then**:
+- it raises `Report::NotAllowed`
+- Bob has no share
+
+#### TC-1.2 A member of another workspace cannot get a share
+**Interface**: Report#share_with (interface)
+**Guards**: "The member must be in the same workspace as the report."
+**Given** Alice owns R. Dan is in another workspace.
+**When** Alice shares R with Dan.
+**Then**:
+- it raises `Report::InvalidMember`
+- Dan has no share
+
+#### TC-1.3 Sharing two times gives one share
+**Interface**: Report#share_with (interface)
+**Guards**: "Sharing with the same member two times gives one share."
+**Given** Alice shared R with Bob.
+**When** Alice shares R with Bob again.
+**Then**:
+- it returns `:already_shared`
+- Bob has one share
+
+#### TC-1.4 A shared member can view, but not edit
+**Interface**: Report#viewable_by? (interface)
+**Guards**: "A shared member can view the report, but cannot edit it."
+**Given** Alice shared R with Bob.
+**When** we ask if Bob can view R, and if Bob can edit R.
+**Then**:
+- `viewable_by?(bob)` is true
+- `editable_by?(bob)` is false
+
+#### TC-1.5 The endpoint maps each result to HTTP
+**Interface**: POST /reports/:id/shares (top)
+**Guards**: the HTTP contract above.
+**Given** the situations of TC-1.1, TC-1.2, and TC-1.3.
+**When** Alice or Carol posts to `/reports/R/shares`.
+**Then**:
+- not the owner: 403
+- a rule fails: 422 with the error
+- an existing share: 200 with the share
+
+## Slice 2: Email the member
+The member gets an email when a report is shared with him or her.
+
+### Goal case
+**Interface**: POST /reports/:id/shares (top)
+**Given** Alice owns R. Bob is in her workspace.
+**When** Alice posts to `/reports/R/shares` with Bob, and the
+background jobs run.
+**Then**:
+- Bob has one email
+- the subject has R's title
+- the body has a link to R
+
+### Cases
+#### TC-2.1 No second email for a duplicate share
+**Interface**: Report#share_with (interface)
+**Guards**: "Sends one email for `:created` only."
+**Given** Alice shared R with Bob, and Bob got the email.
+**When** Alice shares R with Bob again, and the jobs run.
+**Then**:
+- Bob has exactly one email in total
+
+#### TC-2.2 No email when sharing fails
+**Interface**: Report#share_with (interface)
+**Guards**: "Sends one email for `:created` only."
+**Given** the situation of TC-1.1.
+**When** Carol shares R with Bob, and the jobs run.
+**Then**:
+- the mail box is empty
+
+## Findings
+None.
+````

package/skills/productivity/brainstorm/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: brainstorm
+description: Run a structured brainstorm with the user. Pick the framework that fits the situation - starbursting, question formulation (QFT), question burst, pre-mortem, assumption mapping, 5 whys, or six thinking hats. Use when the user wants to brainstorm, make or rank questions, scope research, test a plan, find risks or assumptions, get unstuck, find a root cause, or look at a decision from all sides. Also use when the user names one of these frameworks.
+---
+
+# Brainstorm
+
+If the `simple-english` skill is available, follow it for everything you write for the user.
+
+TODO skill, 2026-09-27. Not built yet.
+
+## 1. Pick the framework
+
+Find what the user wants to do in the table. Then read the reference for that framework.
+
+| The user wants to | Framework | Reference |
+|---|---|---|
+| Find all the unknowns about a goal before work starts | Starbursting | [starbursting](references/starbursting.md) |
+| Make a long list of questions shorter and keep the best | QFT | [question-formulation-technique](references/question-formulation-technique.md) |
+| Get unstuck, or see a problem in a new way | Question burst | [question-burst](references/question-burst.md) |
+| Find how a plan can fail before it starts | Pre-mortem | [pre-mortem](references/pre-mortem.md) |
+| Find which beliefs in a plan to test first | Assumption mapping | [assumption-mapping](references/assumption-mapping.md) |
+| Find the root cause of a problem or a habit | 5 whys | [five-whys](references/five-whys.md) |
+| Look at a decision from all sides | Six thinking hats | [six-thinking-hats](references/six-thinking-hats.md) |
+
+To scope research, use four frameworks in this sequence:
+
+1. Starbursting makes the first list of questions.
+2. Pre-mortem adds questions about how the work can fail.
+3. Assumption mapping adds questions about beliefs that have no proof.
+4. QFT ranks the questions and keeps the most important.
+
+Done when you tell the user the framework name and why it fits, in one sentence.
+
+## 2. Do the brainstorm with the user
+
+Do the steps in the reference. The user gives judgment and context. You give the structure and the pace. You also find the facts that you can look up yourself.
+
+Keep the first phase for ideas only. Give no answers and no opinions in that phase. Each framework exists to stop early judgment.
+
+Done when each step in the reference has its output.
+
+## 3. Give the result to the user
+
+Give the result in the form that the framework makes. This can be a list of questions, a ranked table, or a chain of causes.
+
+Then save it as a note in the vault, under a `brainstorm` folder. Name the file `brainstorm-<topic>.md`, where `<topic>` is a short dash-case name for what the brainstorm was about.
+
+If the brainstorm did not finish all its steps, name the file `brainstorm-<topic>-draft-<yy-mm-dd>.md` instead, using today's date. Move it to the plain `brainstorm-<topic>.md` name once the brainstorm is done.

package/skills/productivity/brainstorm/references/assumption-mapping.md

@@ -0,0 +1,24 @@
+# Assumption mapping
+
+## What it is
+
+This method comes from the book "Testing Business Ideas" by David Bland and Alexander Osterwalder. Write each belief that the plan needs, as a short "we believe that..." statement. Then place each belief on a grid with two axes:
+
+- How important is the belief for the success of the plan? An important belief is one that sinks the plan if it turns out false.
+- How much evidence supports the belief?
+
+Some beliefs are important and have little evidence. These are the leap-of-faith assumptions. Test or research them first.
+
+For engineering work, use Bland's three categories like this: desirability asks whether people (users, or other engineers who must use this) actually want it; viability asks whether it is worth building and keeping, given the maintenance cost; feasibility asks whether the team and the current systems can actually build and run it.
+
+## Steps
+
+1. Write the plan.
+2. Write the assumptions in the three categories: desirable, viable, feasible. Write each assumption as a short, testable "we believe that..." statement. Done when each category has assumptions.
+3. Before placing anything on the grid, check each item: if you can resolve it right now by reading the code, checking the docs, or running a command, it is a fact, not an assumption. Go check it immediately and drop it from the list. Only beliefs that stay unresolved after that check go on the grid.
+4. Put each remaining assumption in a table with columns: assumption, category, importance (high or low), evidence (strong, weak, or none). A markdown table is easier for an agent to produce correctly and easier for the user to scan than a two-axis grid, so use the table, not a drawn grid.
+5. Sort the table so the assumptions with high importance and weak or no evidence sort to the top. For each one, write a test or a research question. The test must prove the assumption or show that it is false.
+
+## Using pre-mortem as a source
+
+Each top cause from [pre-mortem](pre-mortem.md) can become an assumption here: rephrase it as "we believe this cause will not happen" or "we believe we have covered this," then place it on the table like any other assumption.

package/skills/productivity/brainstorm/references/five-whys.md

@@ -0,0 +1,20 @@
+# 5 Whys
+
+## What it is
+
+This method comes from the Toyota Production System (Sakichi Toyoda, Taiichi Ohno).
+
+Start with a statement of the problem. Ask why the problem occurred. Then ask why again about the answer. Continue until the answer names a cause that you can fix.
+
+Five is a guide. You do not have to ask exactly five times. Do not stop just because you reached five; a shallow answer at five is not a root cause.
+
+The method has two well-known weak points. First, a single chain assumes one cause leads to the next in a straight line, but real problems often have more than one contributing cause at a step. When a "why" has more than one true answer, branch into a tree instead of forcing one chain; follow each branch down on its own. Second, people stop as soon as they can name a person or team to blame, such as "the reviewer missed it." A name is never a root cause. When an answer names a person or team, ask why one more time: what missing check, unclear rule, or absent training let that happen. Stop only when the answer names something you can fix in the system, not in a person.
+
+This also works for finding the reason behind a habit or a style choice, not only a failure. Use the same steps, but replace "the problem" with "the choice" and "occurred" with "was made."
+
+## Steps
+
+1. Write the problem (or the choice) as a specific statement of what occurred (or was made).
+2. Ask why. Answer with evidence. Do this again. If an answer names a person or a team, ask why once more instead of stopping there. If an answer splits into more than one true cause, branch into a tree and follow each branch down. Done when each branch ends in a cause that you can fix, and a fix for that cause stops the problem.
+3. Check each link from the bottom up. Make sure that each cause really makes the result above it.
+4. Name the fix for the root cause of each branch.

package/skills/productivity/brainstorm/references/pre-mortem.md

@@ -0,0 +1,21 @@
+# Pre-mortem
+
+## What it is
+
+Gary Klein published this method in Harvard Business Review in 2007 ("Performing a Project Premortem"). Think that it is some months in the future and the plan failed badly. Each person writes the reasons for the failure. Klein's point: making the team assume failure is a fact, not just a risk, makes people name problems they would otherwise soften or stay quiet about, because a dissenter now looks observant instead of disloyal.
+
+When the failure is a fact and not only a possibility, people name risks that they otherwise make smaller. Each cause becomes a risk to control or a question to research.
+
+## Steps
+
+1. Write the plan. Write what success is.
+2. Say that the plan failed. Write as many different causes as possible. Use categories that fit software and agent work: technical (bugs, integration, performance, data loss), scope (unclear or changing requirements), adoption (people do not use or trust the result), maintenance (nobody keeps it working after launch), and agent-specific (the skill does not trigger, the agent misreads the task, the agent uses the wrong tool, the instructions are ambiguous). Done when each category has causes.
+3. For each cause, check it is specific: it must name a concrete mechanism and a sign you would notice, not a general trait. "Bad communication" is not specific. "The reference file assumes a group of five, so a solo agent skips the red-hat step" is specific. If a cause is generic, ask why it would happen one more time, the way [5 whys](five-whys.md) does, until it names something concrete.
+4. Rank the causes by how likely they are and how much damage they do.
+5. For each cause at the top, write one of these:
+   - An action that controls the risk.
+   - A question that you must answer before the work starts.
+
+## Feeding the output onward
+
+Turn any top cause you cannot control outright into a belief statement, such as "we believe the skill will trigger correctly without a worked example," and hand it to [assumption mapping](assumption-mapping.md) to place on the grid. Turn any cause that still needs a fact to resolve into a line in the research brief that [QFT](question-formulation-technique.md) produces.

package/skills/productivity/brainstorm/references/question-burst.md

@@ -0,0 +1,23 @@
+# Question Burst
+
+## What it is
+
+Hal Gregersen made this method at MIT. His book is "Questions Are the Answer". The original has three parts: set the stage (pick a challenge you care about, invite people to help), a four-minute burst of questions with two rules (no one answers, no one explains why they ask), and a close. Gregersen also has people write down how they feel about the problem before the burst and again after it, to see if their view shifted.
+
+First, the user describes the problem in a short time. Then you write as many questions as possible in a short burst. Give no answers and no explanations. After the burst, find the questions that change how the user sees the problem.
+
+The purpose is to break the current view of the problem. Coverage is not the purpose.
+
+An agent has no clock, so use a question count instead of a time limit: a minimum of 15 questions stands in for the four minutes. Keep the before/after feelings check, but ask the user directly, since only the user has a feeling about the problem: ask for one word or one short phrase for how they feel about the problem before the burst, and ask again after. A shift in that word is a sign the burst worked, alongside the marked questions.
+
+## Steps
+
+1. The user describes the problem in a sentence or two. Ask the user for one word or short phrase for how they feel about it right now.
+2. Write a minimum of 15 questions. Write questions only, no answers and no explanation for why you asked. Done when you have 15 questions.
+3. Mark the questions that show the problem in a new way, not just questions that are merely interesting. A question shows a new view when it challenges an assumption the user has not stated, asks about the opposite of the current approach, or reframes the goal itself rather than a detail of it. An interesting-but-not-new question stays inside the current framing and only asks for more detail. Write why for each marked question.
+4. Change the one or two best questions into a next step.
+5. Ask the user again for one word or short phrase for how they feel about the problem now. Note any shift.
+
+## When to use this vs. starbursting
+
+Use question burst when the user is stuck on a problem they already understand and needs a new angle. Use [starbursting](starbursting.md) when the work is new and the goal is full coverage of the unknowns, not a shift in view.

package/skills/productivity/brainstorm/references/question-formulation-technique.md

@@ -0,0 +1,27 @@
+# Question Formulation Technique (QFT)
+
+## What it is
+
+Dan Rothstein and Luz Santana, at the Right Question Institute, made this method. It makes questions, then improves them and ranks them. The official version has five steps: build a focus (called a QFocus), produce questions, improve questions, prioritize questions, and decide next steps.
+
+It has four rules for the phase that makes questions:
+
+- Ask as many questions as possible.
+- Do not stop to discuss, judge, or answer a question.
+- Write each question exactly as you first say it.
+- Change each statement into a question.
+
+An agent runs the same steps but keeps a stricter split than a group does, because one mind is doing both jobs. Treat step 2 (produce) and step 5 (prioritize) as two separate passes with nothing in between. During step 2, write every question down even if it looks weak, obvious, or already answered; do not skip a question because you judge it bad, and do not silently improve it either. Only in step 5, once the full list exists, switch into judging mode and rank what is on the page.
+
+## Steps
+
+1. Start from a focus (QFocus). The focus is a statement or a goal, not a question.
+2. Write questions and obey the four rules. Done when no more questions come. Do not judge or filter while writing.
+3. Mark each question as closed or open. A closed question has a yes, no, or one-word answer.
+4. Change some closed questions to open questions, and some open questions to closed questions. Write what each type is good for.
+5. Choose the three best questions. For research questions, rank against these criteria: how directly the answer serves the goal, whether the answer needs real investigation rather than a quick look-up, how much the answer would change the next step if it came back the opposite of expected, and whether the question overlaps with one already chosen. Give the reason for each choice.
+6. Write what the three questions are for.
+
+## Chaining with other frameworks
+
+Use [starbursting](starbursting.md) first to generate the raw question list across who/what/where/when/why/how, then run QFT's improve and prioritize steps (3 to 6) on that list instead of a fresh produce step. Use [assumption mapping](assumption-mapping.md) after QFT when the question is really about an unproven belief. QFT ranks by research value; assumption mapping ranks by importance and evidence. Run QFT first to cut noise, then assumption mapping on what is left if some questions are really assumptions in disguise.

package/skills/productivity/brainstorm/references/six-thinking-hats.md

@@ -0,0 +1,24 @@
+# Six Thinking Hats
+
+## What it is
+
+Edward de Bono made this method. Each hat is one type of thinking. Use one hat at a time, so that the types do not mix.
+
+The method was written for a group, so each hat is normally one voice among many at the same time. One agent can still run it alone: the agent plays every hat in turn, one after another, the same way the blue hat already forces a fixed sequence in a group. The main thing lost by going solo is the parallel view: several people wearing the same hat at once catch things one mind under that hat misses. There is no fix for that beyond asking the user to add their own view under a hat if they want to.
+
+This method fits a decision better than it fits making research questions. Its risk and benefit hats (black and yellow) call for weighing options the user has already named, not for surfacing unknowns. Reach for it after the user already has a plan or a choice in front of them. For open research scoping, prefer the sequence in the main [SKILL.md](../SKILL.md): starbursting, pre-mortem, assumption mapping, then QFT.
+
+| Hat | Type of thinking |
+|---|---|
+| White | Facts, and the information that is missing |
+| Red | Feelings and first reactions |
+| Black | Risks, and why the idea can fail |
+| Yellow | Benefits, and why the idea can work |
+| Green | New ideas and alternatives |
+| Blue | Process: what to think about next, and the conclusions |
+
+## Steps
+
+1. Blue hat: write the decision and the sequence of hats.
+2. Use each hat in the sequence. Stay in the type of thinking for that hat. For the red hat, an agent has no real gut feeling of its own, so ask the user for their instinctive reaction in one short line, with no justification attached, and write that down as the red hat's output. Done when each hat has output.
+3. Blue hat: write a summary. Make the decision, or name what is still unknown.

package/skills/productivity/brainstorm/references/starbursting.md

@@ -0,0 +1,19 @@
+# Starbursting
+
+## What it is
+
+Starbursting makes questions only. Put the goal at the center of a star with six points. Each point is one question word: who, what, where, when, why, how.
+
+Write questions for each point. Write no answers. The value is coverage. A point with no questions shows a blind spot.
+
+No single named inventor of starbursting turned up in a search of primary sources. The "Lawrence Eggleton" attribution that some sites repeat could not be confirmed anywhere and looks unfounded. Treat starbursting as a named variant of the standard 5W1H (who, what, where, when, why, how) checklist, not as one person's method. Common variants pair it with SWOT, or run it right before QFT to cut the list down.
+
+For one agent and one user: the user gives the goal and the context, and answers any question the agent cannot look up. The agent asks for one question word at a time so the user is not shown 20 questions at once, and writes down what it can already answer from the codebase or docs separately, outside the starbursting list.
+
+## Steps
+
+1. Write the goal in one sentence at the center.
+2. For each of the six points, write 3 to 5 questions only. Done when each point has questions, or a note that it does not apply. Stop a point early if new questions start repeating earlier ones. Do not explain or answer any question in this step, even ones you already know the answer to. If you catch yourself writing an answer, delete it and turn it back into a question.
+3. Add more questions under the questions that open new branches.
+4. Give the list to the user. Group the questions by point. Give no answers. Answer any question you already know the answer to only after the list is complete, and only if the user asks for it.
+5. Always chain into [QFT](question-formulation-technique.md) next to rank the list. Six points at 3 to 5 questions each give at least 18 questions, so the list is long enough to need ranking every time.

package/skills/productivity/caveman/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: caveman
+description: >
+  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
+  filler, articles, and pleasantries while keeping full technical accuracy.
+  Use when user says "caveman mode", "talk like caveman", "use caveman",
+  "less tokens", "be brief", or invokes /caveman.
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+### Examples
+
+**"Why React component re-render?"**
+
+> Inline obj prop -> new ref -> re-render. `useMemo`.
+
+**"Explain database connection pooling."**
+
+> Pool = reuse DB conn. Skip handshake -> fast under load.
+
+## Auto-Clarity Exception
+
+Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
+
+Example -- destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Caveman resume. Verify backup exist first.

package/skills/productivity/simple-english/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: simple-english
+description: Write responses in ASD-STE100 Simplified Technical English - short sentences, active voice, one idea per sentence, simple approved words. Use when the user asks for simple English, plain English, Simplified Technical English or STE, asks to simplify wording or write for non-native readers, or invokes /simple-english.
+---
+
+# Global Instructions
+
+## Communication Style
+
+Write all responses in ASD-STE100 Simplified Technical English:
+- Use short, simple sentences (max ~25 words each).
+- Use active voice.
+- One instruction or idea per sentence.
+- Use simple, approved words. Avoid jargon when a simpler word exists.
+- Be specific and concrete. Avoid vague language.