lv-bug

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bug Filer Role

**`help` / `--help`:** if that is the whole argument, print the `## Usage` block at the end of this file verbatim and stop.

You are in **bug filing mode**. Your job is to capture a bug clearly and completely so it can be triaged, planned, and fixed.

## Two modes

### Quick-fire mode
If the user provides a one-liner or brief description, extract what you can and fill in the rest as `TBD`. Create the bug immediately — don't interrogate them for every field.

### Structured mode
If the user says "new bug" or provides no description, prompt for:
1. **Title** — short, specific (e.g. "Login crashes on empty password")
2. **Project** — which repo or app
3. **Severity** — Critical / High / Medium / Low
4. **Description** — what's broken and the impact
5. **Steps to reproduce** — numbered list
6. **Expected vs actual** — what should happen, what does happen
7. **Links** (optional) — if related to another bug or plan (e.g. "caused by BUG-003", "discovered during debug of BUG-002", "regression from PLN-005")
8. **Attachment** — ask if there's a file to attach (screenshot, log, export)

## Folder structure

```
bugs/open/    → new bugs land here (you create here)
bugs/triaged/ → picked up by /lv-spec when a fix plan is created
bugs/closed/  → resolved by /lv-deploy when a plan completes
```

## What you do

1. **Check branch** — save current branch and switch to develop if needed:
   ```bash
   eval "$(scripts/lv-exec.sh lv-branch-check.sh develop true)"
   ```
   This sets CURRENT_BRANCH (original) and SWITCHED_FROM (if it switched).
2. **File it — one call.** This allocates the ID through the counter, writes `bug.md` in the shape the rest of the pipeline parses, and commits it:
   ```bash
   eval "$(scripts/lv-exec.sh lv-bug-new.sh "<title>" \
     --severity Critical|High|Medium|Low \
     --project "<repo or app>" \
     --description "<what's broken and the impact>" \
     --steps "<numbered list, or TBD>" \
     --expected "<what should happen>" \
     --actual "<what does happen>" \
     --links "<optional: caused by BUG-NNN, regression from PLN-NNN…>")"
   ```
   It sets `$BUG_ID` and `$BUG_DIR`. Omitted fields land as `TBD`, which is the right value for something the user did not say — never invent them. The slug comes from the title unless you pass `--slug`.

   **Do not hand-write the folder instead.** The counter is the only allocator, and it is only actually the only allocator if using it is easier than not: client-a filed two bugs by hand and pushed its counter into drift (WFI-133).
3. **Handle attachments** — if the user provides a file path:
   - Copy it into `$BUG_DIR` and append an `## Attachments` section to `$BUG_DIR/bug.md` referencing it relatively: `[filename.ext](./filename.ext)`
   - If the user describes a file they'll add later, add the placeholder `- [ ] Attach: <description>`
   - Then commit the addition: `scripts/lv-exec.sh lv-commit.sh "bug($BUG_ID): attach <filename>" --add "$BUG_DIR"`
4. **Push**:
   ```bash
   git push origin develop
   ```
5. **Restore branch** — if you switched branches in step 1, switch back:
   ```bash
   [ -n "${SWITCHED_FROM:-}" ] && git checkout "$SWITCHED_FROM"
   ```
6. **Confirm** — show the user the bug ID, folder path, and commit hash

## Filing against a dependency, not this project

Sometimes what you're hearing about is not a bug in *this* project — it's a defect or missing
capability in something this project depends on. The standing example: client-e integrating
client-c's OIDC hits a 401 on token refresh. That's client-c's bug, not client-e's,
even though client-e is where it was noticed.

**Recognize it first.** Ask whose code would actually change to fix this. If the answer is a
different repo, this is a dependency report — filing it here means nobody on the other side
ever sees it.

Check this project's `levain.yml` for a `dependencies:` block:
```yaml
dependencies:
  - "client-c:/path/to/client-c"
```
If the project the bug belongs to is listed there, file through the dependency instead of step 2:
```bash
eval "$(scripts/lv-exec.sh lv-dep-bug.sh --host client-c "<title>" \
  --kind bug|request \
  --severity Critical|High|Medium|Low \
  --description "<what's broken and the impact, written for the HOST's reader>" \
  --steps "<numbered list, or TBD>" \
  --expected "<what should happen>" \
  --actual "<what does happen>" \
  --notes "<how this project hit it — a plan ID, a page, a call it made>" \
  [--links "<ticket, decision record, related artifact over there>"] \
  [--amends <BUG-id>])"
```
`--amends <BUG-id>` is for a report that **corrects one already filed in that host** — a common
case, since a correction usually arrives before the host has triaged the original. It links both
sides through the host's own scripts (`Amends <ID>` on the new one, `Amended by <new ID>` on the
named one) rather than hand-editing `Links:` in another project's `bugs/open/`, which is the one
thing a cross-project filer must never do (coordinator WFI-001).
This `cd`s into the dependency's own checkout and runs **its own** `lv-bug-new.sh` through **its
own** `lv-exec.sh` — the bug is allocated through that project's counter and lands in that
project's `bugs/open/`, exactly where its own `/lv-spec` already looks. There is no second inbox
for anyone to learn. It sets `$DEP_BUG_ID`, `$DEP_BUG_HOST`, `$DEP_BUG_PATH`, `$DEP_BUG_DIR`.

It refuses (exit 2) rather than disturb a checkout a human on the other project has parked
somewhere of their own. When that happens nothing is written — say so and stop, don't retry.

**It commits in the host but does not push.** Tell the user a bug was filed in `<host>` at
`$DEP_BUG_PATH/$DEP_BUG_DIR`, and that project's `develop` still needs a `git push` from over
there — that push is that project's call, not something to do from here.

**FILING IS THE LAST ACT, whether it went through `lv-dep-bug.sh` or you `cd`'d into the
dependency by hand.** A session rooted in this project has no standing role in the host's own
pipeline — that project's `/lv-spec` is what turns its bug into a plan, its own `/lv-implement`
builds it, its own registry tracks it. Do not follow the filed bug with a claim, a hand-authored
`plan.md`/`findings.md`/`progress.md`, a `lv-registry-add.sh`, or a review agent run against the
host's checkout — every one of those is that project's own workflow loop, dispatched from a
session actually rooted there (or its own orchestrator), not from here. client-e's WFI-025 did
exactly this against client-c — filed the bug correctly, then kept going and had to revert

From slicedBread-marc/levain, MIT.

More from slicedBread-marc/levain