Add references + disposition fields to decision events for override tracking
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Problem
`decisions.jsonl` already has `supersedes` for full replacements, but there's no way to track when a prior decision was **surfaced during eng review and confirmed, overridden, or modified** by the human. The 757+ decisions in `PLAN_ENG_REVIEW_DECISIONS.md` are a flat log with no links between them.
When `/plan-eng-review` says "you decided X in decision #412, but we discovered Y — what do you want to do?" and the human answers, that answer is a new decision record. But decision #412 and the new decision are independent lines with no reference between them.
## Proposed change
Add two optional fields to `DecisionEvent` in `lib/gstack-decision.ts`:
```ts
references?: string[]; // prior decision IDs this decision was informed by
disposition?: "confirmed" | "overridden" | "modified";
```
Pass them through `validateDecide` (they're already safe — UUIDs and an enum).
Then in `plan-eng-review/SKILL.md`, when the skill surfaces a prior decision and the human responds, log the new decision with `references: [""]` and the appropriate `disposition`.
## What this unlocks
Once you have `references` + `disposition`, everything else falls out:
- **Promotion signal**: a decision with many `confirmed` references across sessions is battle-tested → auto-promote to `DECISION_DEFAULTS.md`.
- **Deprecation signal**: a decision that keeps getting `overridden` is wrong or stale → flag or deprecate.
- **Context-dependent patterns**: confirmed in some contexts, overridden in others → the `rationale` field becomes critical.
- **Reinforcement loop with no extra labeling**: the human never explicitly labels decisions as right or wrong — it happens naturally through ongoing use.
## Scope
- `lib/gstack-decision.ts`: ~10 lines (add fields to interface + passthrough in validate)
- `bin/gstack-decision-log`: likely 0 lines (already passes full JSON through)
- `plan-eng-review/SKILL.md`: ~5 lines of skill prose
- `bin/gstack-decision-search`: optional — show override/confirm counts
The `supersedes` field is proof the architecture already supports this pattern. This just widens it from "full replacement" to "informed by / confirmed / modified."
Contributor guide
Research direction
Start with DecisionEvent and validateDecide in lib/gstack-decision.ts, then read the related flow in plan-eng-review/SKILL.md. Add the optional references and disposition fields and ensure surfaced decisions are logged with them; done means the fields pass validation and the skill prose describes recording the prior decision ID and outcome.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100