garrytan / garrytan/gstack

Add references + disposition fields to decision events for override tracking

Open
#2,678 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.