🤖 Add ticket context routing to workpad skill
When a ticket context is active (user named a ticket, ticket skill opened one, or explicit request), task-scoped artifacts route into the ticket folder while journals and goals stay in the main workpad. Research and specs are a judgment call based on reusability. Also: tighten resolution step 3 to distinguish project-level tickets folder from per-ticket context, add ticket lifecycle to the "does not cover" list, update steering section to include ticket routing.
This commit is contained in:
@@ -18,7 +18,7 @@ Resolve the workpad base directory in this order — stop at the first hit:
|
||||
- `just workpad-folder` (or any equivalent recipe) if a `.justfile` / `Justfile` is present and defines one — `just` loads `.env` automatically.
|
||||
- `printenv WORKPAD_FOLDER` as a last resort. This will only see values exported into the actual process environment.
|
||||
If any of these prints a non-empty path, treat it as the workpad base.
|
||||
3. **Project-local ticket folder.** Some projects keep a sibling folder *outside* the main repo for per-ticket scratch (e.g. `../<repo>-tickets/` or a path the user has mentioned before). If such a folder is configured for this project, prefer placing the workpad inside it (e.g. `<ticket-folder>/workpad/`). When in doubt whether one exists, ask.
|
||||
3. **Project-local tickets folder.** Some projects keep a sibling folder *outside* the main repo for per-ticket scratch (e.g. `../<repo>-tickets/` or a path configured via `GITEA_TICKETS_DIR`). If one is configured, the workpad base is `<tickets-folder>/workpad/` and individual ticket folders sit beside it as `<tickets-folder>/<id>/`. See "Ticket context" below for how those interact. When in doubt whether one exists, ask.
|
||||
4. **`/docs/workpad`** at the project root, if a `/docs` folder already exists.
|
||||
5. **`/.workpad`** at the project root.
|
||||
6. **Otherwise: ask.** If there is no `/docs` folder and no other signal, do not silently create `/docs/workpad/`. Ask the user where the workpad should live, and confirm before creating any folders.
|
||||
@@ -40,10 +40,32 @@ It may also contain any of these, created on demand:
|
||||
- `journals/` — append-only narratives of long-running problems
|
||||
- `research/` — external research, library evaluations, prior art
|
||||
- `specs/` — frozen, unchanging specifications
|
||||
- `tickets/` — per-ticket scratch space
|
||||
- `tickets/` — per-ticket scratch space, one subfolder per ticket id (see "Ticket context")
|
||||
|
||||
If one of these optional folders is needed and doesn't exist yet, create it. Don't create folders speculatively. Treat unknown folders as owned by the user and ignore them.
|
||||
|
||||
## Ticket context
|
||||
|
||||
A **ticket folder** is `<workpad>/tickets/<id>/`, or `<tickets-folder>/<id>/` when the project configures an external tickets directory. It is created on demand once the id is known — no need to ask.
|
||||
|
||||
A ticket context is **active** when any of these holds:
|
||||
|
||||
- the user named the ticket for this session ("we're on #42", "start ticket 42", "this is for PROJ-17");
|
||||
- a ticket skill opened or created the ticket folder earlier in this conversation;
|
||||
- the user explicitly asked for a file to go into the ticket.
|
||||
|
||||
It is **not** active just because a ticket folder exists on disk, or the branch name contains a number. If the work smells ticket-shaped but nobody said so, ask once and stick with the answer. When several tickets have been mentioned, the most recently named one is active. Once active it stays active until the user switches or says otherwise. When you write into a ticket folder, name the ticket in your reply alongside the path.
|
||||
|
||||
With a ticket context active, route by kind:
|
||||
|
||||
- **Into the ticket folder:** `plans/`, `designs/`, `brainstorm/`, `reports/`, `bugs/`. These are about the ticket's work and should close with it.
|
||||
- **Stay in the main workpad:** `journals/` (session-scoped — the narrative often outlives the ticket) and `goals/` (project-scoped — the ticket itself is the goal; don't duplicate it).
|
||||
- **Judgment call:** `research/` and `specs/`. Ask: *would someone on a different ticket want this?* If yes, main workpad. If it only makes sense against this ticket's deliverable, ticket folder. When a ticket produces a spec that outlives it, promote it to the main workpad on close.
|
||||
|
||||
The ticket folder mirrors the workpad's kind subfolders, created on demand, same file naming including date prefixes. The ticket root holds only ticket-level files (`context.md`, etc.) — never loose plans or reports. The "when to create a subfolder" rules still apply within ticket folders (cascades of related files get their own dated subfolder).
|
||||
|
||||
For main-workpad files written under an active ticket context, put the ticket id in the slug (`2026-05-05-14-42-auth-token-leak.md`) so they stay findable from either side.
|
||||
|
||||
## File naming
|
||||
|
||||
Use a `YYYY-MM-DD-hh-` prefix on filenames in `reports/` and `plans/` at minimum. The hour helps when multiple artifacts land on the same day — which is common during active work — and keeps directory listings naturally sorted by recency. Apply the same prefix to `journals/`, `bugs/`, and `research/` entries; it's almost always the right call there too. For `goals/`, `designs/`, and `specs/`, the prefix is optional — these are referred to by name more than by date, so a descriptive slug alone is fine (e.g. `goals/q2-onboarding-flow.md`, `specs/event-schema.md`).
|
||||
@@ -101,12 +123,13 @@ The same default applies to "write a plan", "draft a brainstorm", etc. — the u
|
||||
|
||||
## Steering other skills
|
||||
|
||||
If you're operating under another skill that wants to write a markdown artifact (a research note, a design sketch, a status report), and a workpad exists or is reasonable to create, route the artifact through the workpad rather than that skill's default location. The other skill governs **what goes in the file**; this skill governs **where the file lives and what it's called**. They compose cleanly.
|
||||
If you're operating under another skill that wants to write a markdown artifact (a research note, a design sketch, a status report), and a workpad exists or is reasonable to create, route the artifact through the workpad rather than that skill's default location — including the ticket routing above when a ticket context is active. The other skill governs **what goes in the file**; this skill governs **where the file lives and what it's called**. They compose cleanly.
|
||||
|
||||
## What this skill deliberately does not cover
|
||||
|
||||
- The internal structure or formatting of reports, plans, designs, etc. That's up to the user, the project's conventions, or another skill.
|
||||
- Git workflow for workpad files (whether to commit them, branch them, etc.).
|
||||
- Ticket lifecycle (whether a closed ticket folder moves to `archive/`, how to promote artifacts out of a ticket, etc.).
|
||||
- Tooling for searching or indexing the workpad.
|
||||
|
||||
If the user asks for help with any of those, treat it as a separate concern.
|
||||
|
||||
Reference in New Issue
Block a user