Apply Work Tracking¶
When to use: A repo keeps plan truth in git (
docs/planning/,docs/wip/, optional*.effort.json) but the team also needs a shared board for priorities, phase summaries, and discussion. Retrofit the repo conventions first, then sync the board whenever plan or ADR progress changes.
Instructions¶
Goal¶
Two layers, one contract:
| Layer | Role |
|---|---|
| Git (source of truth) | Plans, ADRs, effort sidecars, decision status |
| External tracker (visibility) | Priorities, rollups, assignees, team views |
The agent never treats the board as authoritative for effort math or decision
text. Numbers come from plan-effort-estimate scripts; prose comes from the
plan/ADR doc.
Pair this skill with plan-effort-estimate whenever
a tracked item has *.effort.json.
Tracker backends¶
| Backend | Status | Reference |
|---|---|---|
| Notion — HoEN Product Board | Active (WU default) | references/notion-hoen-product-board.md |
| GitHub Projects | Planned | TBD — same field mapping, different API |
| Jira | Planned | TBD |
| Slack lists | Planned | TBD |
When retrofitting a repo, pick one primary backend and document it in
AGENTS.md. Additional backends are additive — same Plan ID and repo fields,
different adapter.
Part A — Retrofit repo conventions¶
Run once per consuming repo (or when onboarding a new component).
A1. Choose repo identity on the board¶
Each repo maps to exactly one Component type on the HoEN Product Board (other trackers: equivalent “project” or “component” field).
| Repo (examples) | Component type |
|---|---|
wue-website |
WUE Website |
hoen-assessment |
ImpactStack |
hoen-library |
HoEN Library |
| (future) | HoEN Explorer, engineeringneeds.io, HoEN API |
Product (Notion) is separate: ImpactStack modules (Workshop, Coordinated Assessment, Self Service SaaS) or product-line tags — not the git repo name.
A2. Add agent guidance — AGENTS.md¶
Add a Plans and Notion product board (or generic Plans and work tracking) section. Minimum content:
- Board URL and this repo’s Component type
- Repo paths that hold truth (
docs/planning/,docs/wip/,*.effort.json) - When you update a plan → refresh the linked board card in the same session
- Lookup by Plan ID (= plan slug or ADR id, e.g.
adr-001-article-rendering-and-ssr) - Effort numbers from
validate-effort.mjs/summarize-effort.mjsonly
Copy-paste templates: references/repo-conventions-template.md.
A3. Cross-link from README and CONVENTIONS¶
- README — one paragraph + link to the AGENTS section (contributors skim README first).
- CONVENTIONS.md (or equivalent) — short pointer under documentation / planning.
A4. Link plans and ADRs back to the board¶
When a card exists (or is created), add a Product board (Notion) section near the top of the plan or ADR:
## Product board (Notion)
| Field | Value |
| --- | --- |
| **Notion card** | [Title](https://app.notion.com/...) |
| **Plan ID** | `plan-or-adr-slug` |
| **Component type** | WUE Website |
| **Work type** | Epic · Story · ADR · … |
When status or progress changes in this doc, update the Notion card in the same
session. See [AGENTS.md § Plans and Notion product board](../../AGENTS.md#plans-and-notion-product-board).
ADRs without effort JSON still get a card (Work type = ADR). Progress headline summarises decision rows (accepted / open / superseded).
A5. Exit criteria (retrofit done)¶
- [ ]
AGENTS.mdsection present with correct Component type and board URL - [ ] README + CONVENTIONS cross-link
- [ ] Each actively tracked plan/ADR has Product board section or explicit “no card yet”
- [ ] Effort-backed plans validate:
validate-effort.mjs --scan docs/
Part B — Operate (sync after repo changes)¶
After any session that changes plan progress, ADR status, or effort JSON:
B1. Decide if sync is needed¶
| Repo change | Update tracker? |
|---|---|
*.effort.json step/group/phase status |
Yes — rollups and headline |
| ADR decision status | Yes — Status, Progress headline |
Plan promoted (wip/ → planning/ / archive/) |
Yes — Plan doc URL, Ship note |
| Plan renamed | Yes — Plan ID (card + doc), Plan doc |
| Typo in plan prose only | Usually no |
B2. Resolve the card¶
- Read Plan ID from the plan doc (or derive from filename:
docs/wip/foo.md→foo). - Search the board by Plan ID (and Component type if many repos share one board).
- If no card and the work is Epic/Story/ADR-worthy, create one — do not create Task-level cards for every checklist line unless the team explicitly wants that.
B3. Refresh fields from repo (Notion)¶
Always run effort scripts before writing numbers:
node library/skills/plan-effort-estimate/scripts/validate-effort.mjs \
--input path/to/plan.effort.json
node library/skills/plan-effort-estimate/scripts/summarize-effort.mjs \
--input path/to/plan.effort.json --pretty
Map script output → board properties (full table in references/notion-hoen-product-board.md):
| Source | Notion property |
|---|---|
--pretty JSON / markdown headline |
Progress headline, Current plan phase |
pctComplete, effort/step/phase counts |
Pct complete, Effort done/total, Steps done/total, Phases done/total, Effort remaining |
| Plan slug | Plan ID |
| GitHub blob URL to plan/ADR on default branch | Plan doc |
| Derived board column | Status (Not started / In progress / In review / Done) |
| Optional: stringify sidecar | Effort JSON |
| Sync timestamp | Plan synced at |
Plan doc must be a full GitHub (or hosting) URL — not a repo-relative path.
For ADRs without effort JSON, set Progress headline from the Status table
(e.g. Accepted: article prerender · Open: whole-site SSR).
B4. Same-session rule¶
Plan/ADR commit (or doc save) and board update belong in one agent session when possible. If the board cannot be updated (API limits, manual filter work), note what is stale in the PR or plan doc.
B5. Future automation¶
A sync-plan-to-notion.mjs script may land in this skill folder later. Until then,
sync is agent + Notion MCP or UI. Field mapping in the reference doc is the
contract the script must implement.
Work types and board hygiene¶
| Work type | Typical use |
|---|---|
| Epic | Multi-phase migration or programme |
| Story | Deliverable slice inside an epic |
| Task / Bug | Usually stay in repo/ issue tracker; board optional |
| ADR | Architecture decision record — no effort JSON required |
Keep on board — check for Done items that should stay visible (e.g. ADRs referenced by active work).
Active board views should hide stale Done cards (~60 days) unless Keep on board is set. Complex OR filters may require manual Notion UI setup — see reference doc.
References¶
- Notion HoEN Product Board — schema, IDs, views, MCP notes
- Repo conventions template — AGENTS/README snippets
- plan-effort-estimate — Fibonacci sidecars and scripts
- docs-implementation-tagging — plan doc headers and lifecycle
Exemplar repos (retrofitted):
wue-website— Component type WUE Website; ADR-001 card linked fromdocs/planning/adr-001-article-rendering-and-ssr.mdhoen-assessment— Component type ImpactStack; Product field for ImpactStack modules
Troubleshooting¶
| Symptom | Likely cause | Fix |
|---|---|---|
| Board shows wrong effort totals | Hand-calculated or stale JSON | Run validate-effort.mjs then summarize-effort.mjs; paste script output only |
| Cannot find card | Plan ID mismatch or missing Component type | Align Plan ID with doc slug; filter by Component type |
| Plan doc link broken on card | Relative path or wrong branch | Use full GitHub blob URL on default branch |
| ADR card missing effort fields | ADRs often have no sidecar | Use Work type ADR; headline from Status table only |
| Done cards clutter the board | 60-day filter not applied | Notion UI: (Status ≠ Done) OR (Done AND Last edited ≤ 60d) OR Keep on board |
| Notion MCP filter update wrong | API limited on compound OR filters | Set filter manually in Notion; document in reference |
| Non-Fibonacci effort values | Invalid sidecar | Fix JSON, re-run validate — see plan-effort-estimate troubleshooting |
Error: validate-effort.mjs fails on --scan
Cause: Rollup or step points not on Fibonacci scale
Solution: Adjust *.effort.json to allowed values (1, 2, 3, 5, 8, 13); never bypass validation for board sync