docs: Phase 5 spec and plan for the planning and roadmap view
Two views rather than one chart, because the data forced it: measured on the live database, 1 of 5 live cards has a target date and none has both dates. target_date is client-owned and optional; start_date is only set on Inbox acceptance. A conventional Gantt would render almost empty. So Now/Next/Later is the default and works with zero dates, and the timeline earns its place as clients set dates. From Dave's Gantt reference it takes the quarter header, the Today marker, project grouping with the client's colour, and the per-row completion percentage — which maps onto checklist progress, the one honest source for it. The faint full-width track is load-bearing rather than decorative: it makes a sparse chart read as unscheduled instead of broken. Drag-to-reschedule always writes an activity row naming the owner, because target_date belongs to the client. A developer silently moving a date the client chose is the failure the activity log exists to prevent. Completes the plan set for phases 1 through 5. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
parent
8a2fb46788
commit
d88dc91d7d
2 changed files with 2150 additions and 0 deletions
1921
docs/superpowers/plans/2026-09-17-phase-5-planning-and-roadmap.md
Normal file
1921
docs/superpowers/plans/2026-09-17-phase-5-planning-and-roadmap.md
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -0,0 +1,229 @@
|
|||
# Phase 5 — The Planning and Roadmap View
|
||||
|
||||
**Date:** 2026-09-17
|
||||
**Status:** Draft for review
|
||||
**Phase:** 5 of 5 — the last
|
||||
**Depends on:** Phase 1 (cards, priorities, dates)
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
A planning page that answers two different questions with two views:
|
||||
|
||||
- **"What do I work on first?"** — every project's committed work, across every
|
||||
client, grouped into Now / Next / Later. This is the default.
|
||||
- **"When is this landing?"** — a real time axis for the cards that carry dates,
|
||||
with an explicit lane for everything that does not.
|
||||
|
||||
For a client manager it is the same page scoped to their own projects: what is
|
||||
underway, what is queued, and when the dated items are expected.
|
||||
|
||||
This is the "planning page with timelines" from the developer's original
|
||||
description, adjusted for what the data actually supports — see §2.
|
||||
|
||||
## 2. What the data actually supports
|
||||
|
||||
Measured on the live database before writing this:
|
||||
|
||||
```
|
||||
live cards: 5
|
||||
with a target_date: 1
|
||||
with a start_date: 0
|
||||
with BOTH (a real Gantt bar): 0
|
||||
```
|
||||
|
||||
Demo data, but the shape is structural rather than incidental:
|
||||
|
||||
- `target_date` is **client-owned and optional**. Most cards will never get one,
|
||||
because most cards are the developer's own work and nobody sets a date on them.
|
||||
- `start_date` is only written when a card is **accepted off the Inbox**
|
||||
(Plan 1c). Cards the developer creates directly never have one.
|
||||
|
||||
So a conventional Gantt — a bar from start to finish — has almost nothing to
|
||||
draw. **A timeline alone would look like a broken feature.**
|
||||
|
||||
Hence two views. Now / Next / Later works with zero dates and is always useful;
|
||||
the timeline earns its place as clients start setting dates, and says plainly how
|
||||
many cards it is not showing.
|
||||
|
||||
## 3. Now / Next / Later
|
||||
|
||||
Bands are **derived, never stored**. A stored band is a third thing to keep in
|
||||
sync with the column and the priority, and it would silently drift from both.
|
||||
|
||||
Derivation, first match wins:
|
||||
|
||||
1. **Excluded entirely** — archived cards, cards in the Inbox (an unaccepted
|
||||
request is not committed work), and cards in the Done column.
|
||||
2. **Now** — overdue, or due within seven days. An imminent date outranks where
|
||||
the card sits on the board.
|
||||
3. **Now** — the card is in the later half of the working columns. On the default
|
||||
board that is In Progress and Review.
|
||||
4. **Now** — critical priority.
|
||||
5. **Next** — the card is in the second working column (To Do), or its priority
|
||||
is high.
|
||||
6. **Later** — everything else.
|
||||
|
||||
Using the *position* of a column rather than its name means a renamed or added
|
||||
column still works. The board's own order is the signal; the roadmap reads it
|
||||
rather than keeping a parallel opinion.
|
||||
|
||||
**Inbox cards are counted but not placed.** The page shows "3 requests waiting"
|
||||
with a link, so pending work is visible without implying it is scheduled.
|
||||
|
||||
## 4. The timeline
|
||||
|
||||
A horizontal time axis across the dated cards, with an **undated lane** beside
|
||||
it holding everything else.
|
||||
|
||||
### 4.1 The reference, and what it can and cannot give us
|
||||
|
||||
The developer supplied an annual Gantt template as the target look. Handled the
|
||||
same way as the Hermes build log in Phase 2 — adopted in one list, corrected in
|
||||
another.
|
||||
|
||||
**Adopted:**
|
||||
|
||||
| From the reference | Why it works here |
|
||||
|---|---|
|
||||
| **Quarter header with month subdivisions** | Right granularity for work measured in weeks |
|
||||
| **A "Today" marker** — vertical line with a pill label | The single most orienting element on the chart, and trivial to draw |
|
||||
| **Rows grouped by category, with a coloured left accent** | Becomes **grouped by project**, accented with the client's brand colour — exactly what a cross-client roadmap needs |
|
||||
| **A faint full-width track behind every bar** | Load-bearing here rather than decorative — see below |
|
||||
| **Rounded bars with circular end caps and an inline range label** | Reads as a period rather than a block |
|
||||
| **A KPI strip along the bottom** | Reuses the tile pattern already built in Phase 2c |
|
||||
| **A per-row completion percentage** | We *do* have an honest source for this — see below |
|
||||
|
||||
**The completion percentage is the best idea in that template**, because it maps
|
||||
onto something real: a card's **checklist progress** from Plan 1c. Four subtasks
|
||||
with three ticked is genuinely 75%, computed from the developer's own ticks and
|
||||
not from anything inferred. A card with no subtasks shows no percentage rather
|
||||
than a fabricated one.
|
||||
|
||||
**What the reference cannot give us:**
|
||||
|
||||
Every task in that template has a start *and* an end, which is why it looks
|
||||
dense and confident. Per §2, almost none of our cards will. Copying it literally
|
||||
produces a chart of empty rows.
|
||||
|
||||
So the **faint track is doing real work**: every row draws its full-width track
|
||||
whether or not it has dates, and a date-only card places a marker on it. A
|
||||
sparse chart then reads as *"these are the items, most are not scheduled yet"*
|
||||
rather than as a rendering failure. That is the one adaptation that makes the
|
||||
reference survive contact with this data.
|
||||
|
||||
### 4.2 Drawing rules
|
||||
|
||||
- A card with both `start_date` and `target_date` draws a **bar**, with its range
|
||||
labelled inline as in the reference.
|
||||
- A card with only `target_date` draws a **marker** on its track. This will be
|
||||
most of them.
|
||||
- A card with neither appears in the **undated lane**, which states its own size:
|
||||
"11 cards with no date set".
|
||||
- Overdue items take the warm accent — the same one used on the board and the
|
||||
dashboard, and one of its three sanctioned uses.
|
||||
- Rows are grouped by project and packed so nothing overlaps, with a minimum
|
||||
width per item so short-dated cards stay clickable and labelled.
|
||||
|
||||
### 4.3 The bottom strip
|
||||
|
||||
Four tiles, each computable from data that exists: **total cards**, **done**,
|
||||
**in progress**, and **overdue**.
|
||||
|
||||
The reference's fifth tile is "On Track 54%". The honest equivalent is
|
||||
**dated cards not overdue** — and it must be labelled as exactly that, because
|
||||
"on track" implies a judgement about work nobody has assessed.
|
||||
|
||||
**No effort estimate appears anywhere on this page.** Phase 2's hours are
|
||||
project-level; there is no per-card duration to draw, and inventing a bar width
|
||||
from one would repeat the mistake §2 exists to avoid.
|
||||
|
||||
## 5. Drag to reschedule
|
||||
|
||||
The owner can drag a card along the timeline to change its `target_date`.
|
||||
|
||||
**This overwrites a field the client owns**, which makes the audit trail
|
||||
load-bearing rather than incidental:
|
||||
|
||||
- The change writes an `activity` row with `date_changed`, the **owner** as
|
||||
actor, and the real old and new values — the same shape Plan 1a writes for
|
||||
client edits.
|
||||
- The client's card history therefore reads *"Dave moved the target date from
|
||||
1 Oct to 15 Nov"*, in their own view, without anyone having to tell them.
|
||||
|
||||
A developer silently moving a date the client chose, with no record, is exactly
|
||||
the failure the activity log exists to prevent. The log has always recorded
|
||||
client-originated writes; this phase is the first time the owner routinely
|
||||
changes a client-owned field, so it must record those too.
|
||||
|
||||
Dragging is **owner-only**. A client manager reads the timeline and edits dates
|
||||
where they already can — on the board tile and the card page, through
|
||||
`/api/client/cards/:id`.
|
||||
|
||||
Dragging snaps to whole days. Sub-day precision on a field nobody sets by the
|
||||
hour is false precision.
|
||||
|
||||
## 6. Scope
|
||||
|
||||
| Role | Sees |
|
||||
|---|---|
|
||||
| Owner | Every active project, every client, on one page |
|
||||
| Client manager | Their own client's projects only |
|
||||
|
||||
Scoping is the Phase 1 read rules doing their job, not a UI filter — the loader
|
||||
reads with the caller's own PocketBase token, as every other page does.
|
||||
|
||||
Cross-client is the point for the owner: *"priorities on what I need to work on
|
||||
first or last"* is a question that spans clients. Each card carries its client's
|
||||
brand colour so the page is scannable by customer.
|
||||
|
||||
## 7. Data model
|
||||
|
||||
**No new fields.** Bands are derived, the timeline reads `start_date` and
|
||||
`target_date`, and rescheduling writes `target_date` and an `activity` row —
|
||||
all of which exist.
|
||||
|
||||
This is worth stating because the instinct is to add a `roadmap_order` or a
|
||||
stored band. Both would be a second source of truth for something the board
|
||||
already decides.
|
||||
|
||||
## 8. Out of scope
|
||||
|
||||
- **Per-card effort or duration bars.** §4.
|
||||
- **Dependencies between cards.** No card knows about another, and adding that
|
||||
is a scheduling product, not a progress board.
|
||||
- **Capacity or resource planning.** One developer.
|
||||
- **Reordering priority by dragging between bands.** The bands are derived from
|
||||
column and priority, so dragging between them would have to decide which of
|
||||
those to rewrite — and the board already does that job unambiguously.
|
||||
- **A client-facing export or PDF.** The page is the artefact.
|
||||
|
||||
## 9. Acceptance criteria
|
||||
|
||||
1. The owner sees every active project's committed work on one page, grouped
|
||||
Now / Next / Later, with each card showing its client and project.
|
||||
2. A client manager sees only their own client's cards.
|
||||
3. Archived, Inbox and Done cards are excluded from the bands; Inbox cards are
|
||||
counted and linked.
|
||||
4. Bands follow the board: moving a card from Backlog to In Progress moves it to
|
||||
Now without any stored value changing.
|
||||
5. The timeline draws bars for cards with both dates, markers for date-only
|
||||
cards, and states how many cards it is not showing. Every row draws its
|
||||
track whether or not it is scheduled, so a sparse chart reads as sparse
|
||||
rather than broken.
|
||||
6. A card with subtasks shows its checklist percentage; a card without shows
|
||||
none rather than a fabricated one.
|
||||
7. The bottom strip's fifth figure is labelled "dated cards not overdue", never
|
||||
"on track".
|
||||
8. The owner can drag a card to a new date; a client manager cannot.
|
||||
9. A rescheduled card writes an `activity` row naming the owner, with correct
|
||||
old and new values, visible in the client's card history.
|
||||
10. With no dated cards at all, the timeline tab says so plainly rather than
|
||||
rendering an empty chart.
|
||||
|
||||
## 10. Plan
|
||||
|
||||
One plan — `docs/superpowers/plans/2026-09-17-phase-5-planning-and-roadmap.md`.
|
||||
This phase adds no schema, no provider integration and no new security boundary;
|
||||
splitting it would cost more in coordination than it saves in review.
|
||||
Loading…
Reference in a new issue