Step 03 — Plan: author the brief

← 02 Rehearse offline · Index · next: 04 Do →

Beat: Plan. Human touch point #1. The output is one artifact — brief.md — the contribution spec the rest of the cycle is measured against. A bundle with no brief.md is UNPLANNED; once the brief exists it's PLANNED and ready for Do.

How Plan runs

The Plan leaf is interactive — it opens Claude in your terminal so you and the planner co-author the brief from a tracker issue. gramps configured it to read a single Mantis CSV row for the issue id:

make flow ID=11589        # opens the planner; you converge on a brief, then the
                          # driver continues unattended into Do + Check

Under the hood that's the planner leaf from step 01 writing results/issue_11589/brief.md. You can also seed a brief directly (pdca init-issue 11589 --from-brief path/to/brief.md) when you've written it by hand.

What a real brief looks like

This is the actual brief the planner produced for gramps issue 11589, a PluginManager bug. Read it as a checklist of what a good spec contains — every field earns its place downstream.

# Brief — issue 11589 / pluginmanager-uninstall-destroys-shared-dir

- **Slug:** pluginmanager-uninstall-destroys-shared-dir
- **Defect:** In the enhanced Plugin Manager addon, uninstalling a single add-on
  filter rule deletes the **entire** shared `FilterRules` plugin directory — all
  the other rules in the pack *and* any unrelated user content the user placed
  there. Root cause: `__uninstall` calls `shutil.rmtree(pdata.fpath)` on the
  plugin's *directory* (`PluginManager.py:349`), but `pdata.fpath` is the
  directory shared by every plugin in a multi-plugin pack ...
- **Success criterion:** Uninstalling one plugin whose directory is shared by
  other registered plugins removes only the files belonging to the selected
  plugin; the sibling plugins' files and any unrelated files/sub-folders survive,
  and the directory itself is **not** removed while other registered plugins still
  live in it. (Uninstalling a plugin that is the sole occupant of its own
  directory must still remove the directory, preserving today's behaviour.)
- **Repo + branch target:** addons-source @ `maintenance/gramps60` (addons
  production branch per INTEGRATION §2; maintainer cherry-picks forward to gramps61).
- **Scope:** Make `PluginManager.__uninstall` (`...PluginManager.py:339-358`)
  non-destructive for shared directories ... /
  **out of scope:** repackaging the FilterRules pack; the reporter's secondary
  observation; the core plugin manager; changing the install path.
- **Repro instruction:** With the FilterRules pack installed ... select one rule
  and click Uninstall. Observed: the whole directory is deleted. Expected: only
  the selected rule's files are removed.
- **Test file:** `../addons-source/PluginManager/tests/test_uninstall_shared_dir.py`
  (addon convention per INTEGRATION §3 — `tests/` package, `test_*.py` prefix).

Why each field is there

A brief is not free-form. Each labelled field is consumed by a later beat, which is why the harness can automate Do and Check at all:

Notice how INTEGRATION.md is cited inline — "addons production branch per INTEGRATION §2", "addon convention per INTEGRATION §3". That's the payoff of step 01: the planner resolves abstract questions ("which branch? where does the test go?") against your repo's concretizations instead of guessing.

STOP discipline

Every brief carries the rule that the cycle never ships before sign-off:

Draft only until Check sign-off. A draft PR MAY be opened for CI; the PR MUST NOT be marked ready before sign-off accepts.

The brief is now written. State: PLANNED. The driver advances unattended into the Do beat — step 04.

← 02 Rehearse offline · Index · next: 04 Do →