@kiwidata/grimoire 0.1.1

package/skills/grimoire-bug-report/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: grimoire-bug-report
+description: Structured bug reporting for testers. Guides creation of reproducible, context-rich bug reports that link to existing feature specs. Accepts output from testing tools (Playwright, Cypress, etc.) via MCP or directly. Use when a tester or non-developer needs to file a bug.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-bug-report
+
+Guided bug reporting workflow for testers. Produces structured, reproducible bug reports that developers can act on without back-and-forth. Can ingest test tool output (Playwright traces, Cypress screenshots, API responses, performance reports) to auto-populate reports.
+
+## Triggers
+- A tester or non-developer wants to report a bug
+- User says "report a bug", "file a bug", "I found a bug"
+- User pastes test output, a failing test trace, or a screenshot from a testing tool
+- Loose match: "bug report", "report issue", "found a problem", "something's wrong", "test failed"
+
+## Routing
+- Developer wanting to fix a bug → `grimoire-bug`
+- Developer investigating/triaging → `grimoire-bug-triage`
+- Looking for test gaps proactively → `grimoire-bug-explore`
+
+## Prerequisites
+- A grimoire project (`.grimoire/config.yaml` exists)
+- Ideally, feature files exist in `features/` so the report can reference violated specs
+
+## Workflow
+
+### 1. Check for Test Tool Input
+
+Before starting the interview, check if the reporter is providing output from a testing tool:
+
+**MCP-connected testing tools** — read `.grimoire/config.yaml` for `testing_tools` with MCP servers configured. If a Playwright MCP, Cypress, or other testing tool is available:
+- Offer to pull the latest test results, screenshots, traces, or failure logs directly
+- Use the MCP tools to get structured failure data (failed assertions, screenshots, network logs, console errors)
+- Auto-extract: what failed, reproduction steps (from the test), environment details, and evidence
+
+**Direct test output** — if the reporter pastes or provides:
+- Playwright/Cypress test output → extract the failing test name, assertion, screenshot paths, and trace URL
+- API test output (Postman, Bruno, curl) → extract endpoint, status code, request/response bodies
+- Performance test output (k6, Artillery, Lighthouse) → extract metrics, thresholds breached, and resource URLs
+- Any structured test report (JUnit XML, JSON) → extract failing test cases and error messages
+
+**If test tool input is available**, pre-fill as much of the report as possible and confirm with the reporter rather than asking them to re-describe what the tool already captured. Skip to step 1b for any gaps.
+
+### 1b. Gather Bug Details (Interview)
+
+Walk the reporter through a structured interview for anything not already captured from test tools. Ask these one section at a time — don't dump a template and ask them to fill it out.
+
+**What happened?**
+- What did you observe? (actual behavior)
+- What did you expect instead? (expected behavior)
+
+**How do you trigger it?**
+- Step-by-step reproduction: what actions, in what order?
+- Is it consistent or intermittent?
+
+**Where does it happen?**
+- Which page, endpoint, feature area, or workflow?
+- What environment? (see Environment section below)
+
+**How bad is it?**
+- **critical** — blocks a core workflow, data loss, security issue
+- **major** — significant feature broken, no workaround
+- **minor** — feature works but behaves incorrectly in an edge case
+- **cosmetic** — visual or text issue, no functional impact
+
+**How often does it happen?**
+- **always** — reproduces every time
+- **intermittent** — reproduces sometimes (ask: roughly what percentage? any pattern?)
+- **rare** — happened once or twice, hard to reproduce
+- Intermittent and rare bugs need different investigation strategies — capturing frequency early saves time later.
+
+**Is this a regression?**
+- **yes** — "this used to work" (ask: when did it last work? what changed?)
+- **no** — never worked, or new feature
+- **unknown** — not sure
+
+If yes, this changes priority — regressions mean something broke that was previously working, which usually points to a specific change.
+
+**Is there a workaround?**
+- If the reporter has found a way to accomplish their goal despite the bug, capture it explicitly — this unblocks the team while the fix is pending.
+- Example: "I can export as PDF instead of CSV" or "clearing the cache fixes it temporarily."
+
+**How many users are affected?**
+- **one user** — specific account or configuration
+- **some users** — a subset (ask: what do affected users have in common?)
+- **all users** — everyone hitting this flow
+- This is a severity multiplier — a minor bug affecting all users may outrank a major bug affecting one.
+
+If the reporter provides screenshots, logs, error messages, or network traces — capture those references. Don't require them, but note what's available.
+
+### 1c. Security Screening
+
+After gathering details, check whether this might be a security issue. Look for signals in what the reporter described:
+
+- **Authentication/authorization bypass** — accessing something they shouldn't, or acting as another user
+- **Data exposure** — seeing other users' data, PII in logs, sensitive info in error messages
+- **Injection** — unusual characters causing unexpected behavior (SQL, XSS, command injection)
+- **Credential/secret exposure** — API keys, tokens, or passwords visible in UI, URLs, or logs
+- **Privilege escalation** — performing actions above their role (e.g., normal user accessing admin functions)
+- **Denial of service** — actions that crash or freeze the system for other users
+
+**If any security signals are detected:**
+
+1. **Warn the reporter** — "This looks like it might be a security issue. Security bugs need special handling to avoid exposing the vulnerability before it's fixed."
+2. **Set `security: true`** in the report frontmatter
+3. **Don't include exploit details in public trackers** — if the team's bug tracker is public (e.g., public GitHub repo), note that the full reproduction steps are in the local report only. The external ticket should describe the impact without providing a step-by-step exploit guide.
+4. **Flag for priority triage** — security issues should skip the queue
+
+The reporter doesn't need to make the security determination themselves. This screening happens automatically based on the described behavior. If in doubt, flag it — it's better to over-flag and have triage clear it than to miss a real vulnerability.
+
+### 2. Match to Feature Specs
+
+Search `features/` for scenarios that describe the expected behavior:
+
+1. Read feature files in the area the bug relates to
+2. Identify which scenario(s) the bug violates — quote the specific scenario name(s)
+3. If no scenario covers this behavior, note it as a **spec gap** — this is valuable information for triage
+
+This step is what makes grimoire bug reports better than plain text. Linking a bug to its spec removes ambiguity about what "correct" means.
+
+### 3. Check for Duplicates
+
+Before writing the report:
+1. Check `.grimoire/bugs/` for existing reports in the same area
+2. Check `.grimoire/changes/` for any active bug fixes that might address this
+3. If bug trackers are configured in `.grimoire/config.yaml` (`bug_trackers` with MCP), search the external tracker for similar issues
+4. Search git log for recent commits mentioning the same area
+5. If a potential duplicate exists, flag it to the reporter and ask if it's the same issue
+
+### 4. Write the Bug Report
+
+Create `.grimoire/bugs/<bug-id>/report.md`:
+
+```markdown
+---
+id: <bug-id>
+status: reported
+severity: <critical|major|minor|cosmetic>
+frequency: <always|intermittent|rare>
+regression: <yes|no|unknown>
+security: <true|false>
+environment: <dev|qa|staging|production>
+affected-users: <one|some|all>
+reported-by: <name or role>
+date: <YYYY-MM-DD>
+area: <feature area>
+source: <manual|playwright|cypress|postman|k6|other>
+ticket: <external ticket URL or ID, if created>
+---
+
+# Bug: <short descriptive title>
+
+## What Happens
+<Actual behavior — what the reporter observed>
+
+## What Should Happen
+<Expected behavior — ideally referencing a feature spec>
+
+## Reproduction Steps
+1. <step>
+2. <step>
+3. <step>
+
+## Environment
+- **Target**: <dev|qa|staging|production>
+- **Browser/Client**: <browser, OS, API client, mobile device>
+- **Config**: <relevant feature flags, user role, tenant, data conditions>
+- **Version/Build**: <commit SHA, release tag, deploy timestamp — whatever identifies the build>
+
+## Violated Specs
+<!-- Which feature scenarios describe the expected behavior? -->
+- `features/<area>/<file>.feature`: "Scenario name"
+<!-- Or: No existing scenario covers this behavior (spec gap) -->
+
+## Evidence
+<!-- Screenshots, logs, error messages, network traces — whatever the reporter provided -->
+<!-- For test tool output: include trace URLs, screenshot paths, assertion details -->
+- <evidence description and location>
+
+## Test Tool Output
+<!-- Omit this section if the bug was reported manually -->
+- **Tool**: <playwright|cypress|postman|k6|other>
+- **Test**: <test name or ID that failed>
+- **Assertion**: <what the test expected vs what it got>
+- **Artifacts**: <paths to screenshots, traces, HAR files, recordings>
+
+## Workaround
+<!-- Omit if none. Capture any way the reporter can accomplish their goal despite the bug. -->
+<workaround or "None known">
+
+## Reporter Notes
+<!-- Anything else the reporter mentioned — related issues, context -->
+<notes>
+```
+
+**Bug ID format:** `bug-<short-description>` (kebab-case, e.g., `bug-login-timeout-on-2fa`, `bug-csv-export-missing-headers`)
+
+### 5. Confirm with Reporter
+
+Show the completed report to the reporter and ask:
+- Does this accurately describe what you saw?
+- Anything to add or correct?
+
+Make edits if needed. The goal is that a developer can pick this up without needing to ask the reporter any questions.
+
+### 6. Notify
+
+Check `.grimoire/config.yaml` for configured `bug_trackers` with MCP servers. If available:
+- Create a ticket/issue in the configured tracker from the report
+- Link the local bug report to the external ticket (update the `ticket:` field in frontmatter)
+- Post a notification to the relevant channel if a communication MCP is available
+
+If multiple bug trackers are configured, ask which one to use for this report.
+
+**Security reports get special handling:**
+- If the bug tracker is public (e.g., public GitHub repo), do NOT create a public ticket. Use GitHub's private security advisory feature, or create the ticket in a private tracker only.
+- The external ticket should describe the **impact** ("users can access other users' data") without the **exploit** ("by changing the user_id parameter in the URL to another user's ID").
+- Full reproduction steps stay in the local `.grimoire/bugs/` report only.
+- If a private security channel exists (e.g., `#security` Slack channel, private Jira project), notify there instead of the general channel.
+
+If no MCP tools are configured, tell the reporter the report is at `.grimoire/bugs/<bug-id>/report.md` and they can share it however they normally would.
+
+## Important
+- **The reporter is not a developer.** Don't ask for stack traces, code references, or technical root causes. Ask for what they saw and how to see it again.
+- **Don't diagnose during reporting.** This skill captures the bug. Diagnosis happens in `grimoire-bug-triage`.
+- **Severity is the reporter's assessment.** The developer may reclassify during triage, and that's fine.
+- **Environment matters.** A bug on production is different from a bug on dev. Always capture which environment.
+- **Link to specs, not code.** Feature files are readable by testers. Source code references are not helpful here.
+- **One bug per report.** If the reporter describes multiple issues, create separate reports.
+- **Test tool output is evidence, not the report.** Even with rich test output, the report should be human-readable. The test output goes in the Evidence/Test Tool Output sections.
+
+## Done
+When the report is confirmed by the reporter and saved to `.grimoire/bugs/`, the workflow is complete. Suggest `grimoire-bug-triage` to classify and route the bug.

package/skills/grimoire-bug-session/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: grimoire-bug-session
+description: Guided exploratory testing sessions with charter, progress tracking, session notes, and debrief. Use when a tester wants to spend focused time exploring an area of the application.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-bug-session
+
+Guided exploratory testing sessions. Create a charter, track coverage as you work, take notes, file bugs inline, and produce a session debrief when the timebox expires. This is the difference between "I poked around for an hour" and "I systematically explored auth for 45 minutes and here's what I found."
+
+## Triggers
+- User wants to do a focused exploratory testing session
+- User says "start a testing session", "explore [area] for [time]", "session-based testing"
+- Loose match: "testing session", "session charter", "timebox testing", "exploratory session", "let's explore"
+
+## Routing
+- Want AI analysis of specs/code without interactive testing → `grimoire-bug-explore`
+- Want to file a specific bug → `grimoire-bug-report`
+- Want to fix a bug → `grimoire-bug`
+
+## Prerequisites
+- A grimoire project with feature files in `features/`
+- Ideally, a previous `grimoire-bug-explore` run or knowledge of what areas are risky (but not required)
+
+## Workflow
+
+### 1. Create the Charter
+
+A session charter defines the mission before the tester starts clicking. Ask the tester:
+
+**Mission** — What are you trying to learn or find?
+- "Find edge cases in the checkout flow"
+- "Explore what happens with large datasets in reporting"
+- "Test the new auth changes for regressions"
+
+If the tester isn't sure, help them pick a mission based on:
+- Areas flagged by `grimoire-bug-explore` (if a findings report exists)
+- Recent changes (`git log --since="1 week ago"`)
+- Open bugs in `.grimoire/bugs/` that might indicate broader issues
+- Areas with sparse automation coverage (feature files with few or no step definitions)
+
+**Scope** — What's in bounds and what's out?
+- In: specific feature areas, pages, workflows, API endpoints
+- Out: explicitly exclude areas that aren't the focus (reduces scope creep)
+
+**Timebox** — How long?
+- Suggest 30-60 minutes for focused sessions. Shorter than 20 minutes is too shallow; longer than 90 minutes leads to fatigue.
+- The timebox is a guide, not a hard stop. But the skill will prompt a wrap-up when time is close.
+
+**Risk areas** — What are you especially watching for?
+- Performance under load, data integrity, permission bypasses, error handling, cross-browser issues
+- Pull from `grimoire-bug-explore` findings if available
+
+Create the session directory and charter:
+
+```
+.grimoire/sessions/<session-id>/charter.md
+```
+
+```markdown
+---
+id: <session-id>
+status: active
+tester: <name or role>
+started: <YYYY-MM-DD HH:MM>
+timebox: <N> minutes
+area: <feature area>
+---
+
+# Session: <mission summary>
+
+## Mission
+<What are we trying to learn or find?>
+
+## Scope
+- **In**: <what's included>
+- **Out**: <what's excluded>
+
+## Risk Areas
+- <specific risks to watch for>
+
+## Test Ideas
+<!-- Seeded from explore findings, specs, and risk areas -->
+- [ ] <test idea 1>
+- [ ] <test idea 2>
+- [ ] <test idea 3>
+- [ ] <test idea 4>
+- [ ] <test idea 5>
+```
+
+**Session ID format:** `session-<area>-<YYYYMMDD>` (e.g., `session-auth-20260411`, `session-checkout-20260411`)
+
+### 2. Seed Test Ideas
+
+Before the tester starts, generate a list of things to try based on:
+
+1. **Feature specs** — read scenarios in the scoped area. For each happy path, suggest the corresponding negative/edge cases (same analysis as `grimoire-bug-explore` step 2, but targeted to the session scope).
+
+2. **Automation coverage** — check which scenarios have step definitions and which don't. Prioritize manually testing what isn't automated.
+
+3. **Explore findings** — if a `grimoire-bug-explore` report exists for this area, pull in the flagged gaps as test ideas.
+
+4. **Recent changes** — `git log` the area's implementation files. Recent changes → specific things to test.
+
+5. **Open bugs** — check `.grimoire/bugs/` for reports in this area. Related bugs suggest patterns to probe.
+
+Add these as checkable items in the charter. The tester can add their own as they go.
+
+### 3. Track Progress During the Session
+
+As the tester works, they'll report what they're doing and finding. Track this in real time:
+
+**When the tester reports trying something:**
+- Check off the test idea if it matches one in the charter
+- Update the coverage map: "you've covered 4 of 7 test ideas in this area"
+- Suggest what's left: "you haven't tried the error cases yet — want to explore those next?"
+
+**When the tester finds something interesting:**
+- Capture it as a session note in `.grimoire/sessions/<session-id>/notes.md`:
+  ```markdown
+  ## Notes
+
+  ### <HH:MM> — <short description>
+  <what the tester observed>
+  <why it's interesting>
+  ```
+
+**When the tester finds a bug:**
+- Offer to file it immediately via `grimoire-bug-report` (the session context pre-fills the report: area, environment, what they were doing)
+- Track it in the session: "Bug filed: `bug-<id>` — <title>"
+- Don't interrupt the session flow — file quickly and keep exploring
+
+**When the tester goes off-charter:**
+- This is fine — exploratory testing should follow interesting threads. Note the detour but don't block it.
+- If they've strayed far from the mission, gently note it: "You've moved into the reporting area — that's outside the session scope. Want to add it to scope or note it for a separate session?"
+
+### 4. Timebox Management
+
+LLMs cannot track wall-clock time. Use interaction counting as a proxy:
+
+- **Set a checkpoint interval** at charter creation: every N interactions (suggest 8-10), pause and summarize progress.
+- **At each checkpoint**: report test ideas covered vs remaining, suggest what to prioritize next.
+- **After 3 checkpoints** (or when the user signals): prompt wrap-up and debrief.
+- **The user controls pacing.** They can say "keep going", "wrap up", or "extend". The skill tracks coverage, not the clock.
+
+### 5. Generate Session Debrief
+
+When the session ends (timebox or tester decides to stop), produce a structured debrief:
+
+Create `.grimoire/sessions/<session-id>/debrief.md`:
+
+```markdown
+---
+id: <session-id>
+status: completed
+tester: <name or role>
+started: <YYYY-MM-DD HH:MM>
+ended: <YYYY-MM-DD HH:MM>
+duration: <actual minutes>
+area: <feature area>
+bugs-filed: <count>
+---
+
+# Session Debrief: <mission summary>
+
+## Coverage
+- Test ideas completed: <N> of <total>
+- Test ideas skipped: <list with reasons>
+- Areas explored outside charter: <list>
+
+## Bugs Filed
+- `<bug-id>`: <title> (<severity>)
+- `<bug-id>`: <title> (<severity>)
+
+## Observations
+<!-- Interesting things that aren't bugs but are worth noting -->
+- <observation>
+
+## Risks Identified
+<!-- Things that need more investigation or a separate session -->
+- <risk>
+
+## Automation Gaps Discovered
+<!-- Scenarios or behaviors that should be automated but aren't -->
+- <gap> — suggested scenario: `<Given/When/Then>`
+
+## Recommendations
+- <what to explore next>
+- <what to automate>
+- <what to escalate>
+
+## Session Quality
+- **Charter adherence**: <stayed focused / moderate detours / significant scope change>
+- **Time usage**: <efficient / some idle time / ran long>
+```
+
+Update the charter status to `completed`.
+
+### 6. Follow-Up
+
+After the debrief:
+
+- **Bugs filed during the session** are already in `.grimoire/bugs/` — they'll flow through normal triage.
+- **Automation gaps** — offer to create the missing scenarios now (via `grimoire-bug-explore` step 6 workflow) or add them to a backlog.
+- **Follow-up sessions** — if significant areas were skipped, suggest a follow-up session with a new charter.
+- **Link to explore** — if this session revealed patterns (e.g., "error handling is weak across the board"), suggest a broader `grimoire-bug-explore` run.
+
+## Important
+- **The tester drives the session.** The skill guides and tracks, but doesn't dictate what to test next. Suggest, don't command.
+- **Notes are lightweight.** Don't ask the tester to write essays. A timestamp and a sentence is enough. The skill fills in structure.
+- **File bugs fast.** When the tester finds something, capture it in 30 seconds and get back to exploring. Don't let bug reporting break the flow.
+- **The charter is a guide, not a contract.** Good exploratory testing follows interesting threads. Track detours but don't prevent them.
+- **Sessions are not test plans.** A test plan is comprehensive and repeatable. A session is focused and adaptive. Don't try to cover everything in one session.
+- **Debrief is mandatory.** The value of a session is in the debrief — what was found, what wasn't covered, what to do next. Without it, the session is just unstructured clicking.
+- **Respect the timebox.** Sessions without time limits become aimless. The timebox creates focus and urgency. Extend if productive, but always be conscious of time.
+- **Build on previous sessions.** Check `.grimoire/sessions/` for past sessions in the same area. What was covered before? What was flagged for follow-up?
+
+## Done
+When the session debrief is generated and follow-up actions are identified, the workflow is complete. The debrief is saved to `.grimoire/sessions/`. Bugs filed during the session flow through normal triage.