feat(office-hours): design docs land in the repo, written as decision records (#703, #2000)

Office-hours Phase 5 now dual-writes the design doc: the docs/designs/ copy
is what teammates and plan reviews read (committable, visible), while the
~/.gstack copy keeps memory ingest and cross-session discovery working. The
repo copy leaves the private store, so it passes the redaction scan-at-sink
first (HIGH blocks the repo copy, MEDIUM confirms per finding), and any
failure — read-only checkout, non-git dir, unconfirmed finding — degrades
to the private copy with a one-line reason, never blocking the handoff.

The doc itself is now a decision record, not a transcript: one bullet per
decision with its why, ruled-out approaches collapsed to a single line with
the rejection reason, settled/empty template sections omitted. No page cap;
extra length must come from genuinely open questions.

Plan reviews (ceo/eng/devex + the shared review resolver) prefer the
repo-local doc (DESIGN.md, then newest docs/designs/*.md) when it's at
least as fresh as the private copy — a stale old repo doc never shadows a
newer session. Parity guards bumped with measured values (three plan-review
skeletons +~0.7KB each; office-hours 1.092x).

Judgment ported from time-attack/gstack (GStack 2); scan-at-sink and
freshness-preference adaptations ours.

Co-authored-by: Sina Matian <sina@time-attack.dev>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-08-14 13:06:37 -07:00
co-authored by Sina Matian Claude Fable 5
parent 357498803d
commit 4a34bd7d36
11 changed files with 230 additions and 32 deletions
+26 -2
View File
@@ -19,8 +19,32 @@ If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This
Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`.
After writing the design doc, tell the user:
**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
**Repo copy (dual-write, #703 + #2000).** When the session runs inside a git
repository, ALSO write the doc to `docs/designs/{topic-slug}.md` in the repo —
visible, committable, team-shareable. The `~/.gstack` copy is still written
(memory ingest and cross-session discovery depend on it); the repo copy is
what teammates and plan reviews read. Rules:
1. **Scan at sink first.** The repo copy leaves the private store, so scan the
EXACT bytes before writing: write to a temp file, run
`~/.claude/skills/gstack/bin/gstack-redact --from-file <tmp>`; exit 3
(HIGH) blocks the repo copy (keep the ~/.gstack copy, tell the user why);
exit 2 (MEDIUM) confirms per finding before writing.
2. **Fallback is never blocking.** Read-only checkout, non-git directory, a
failed write, or an unconfirmed MEDIUM → keep the `~/.gstack` copy and say
in one line why the repo copy was skipped. The handoff continues either way.
3. **Name the repo path** in the handoff line and any approval questions when
the repo copy exists — that's the copy the user can open and commit.
**Decision-record concision (#2000).** The doc is a decision record, not a
transcript: one bullet per decision with its why; an approach the user ruled
out DURING the session gets one line (name + rejection reason), never a
resurrected full section that re-argues the case; omit template sections that
are empty or that restate what's already settled. No page cap — extra length
must come from genuinely open questions, not template completeness.
After writing, tell the user:
**"Design doc saved to: {repo path if written, else ~/.gstack path}{when both: ' (cross-session copy in ~/.gstack)'}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
### Startup mode design doc template:
@@ -17,8 +17,32 @@ If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This
Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`.
After writing the design doc, tell the user:
**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
**Repo copy (dual-write, #703 + #2000).** When the session runs inside a git
repository, ALSO write the doc to `docs/designs/{topic-slug}.md` in the repo —
visible, committable, team-shareable. The `~/.gstack` copy is still written
(memory ingest and cross-session discovery depend on it); the repo copy is
what teammates and plan reviews read. Rules:
1. **Scan at sink first.** The repo copy leaves the private store, so scan the
EXACT bytes before writing: write to a temp file, run
`~/.claude/skills/gstack/bin/gstack-redact --from-file <tmp>`; exit 3
(HIGH) blocks the repo copy (keep the ~/.gstack copy, tell the user why);
exit 2 (MEDIUM) confirms per finding before writing.
2. **Fallback is never blocking.** Read-only checkout, non-git directory, a
failed write, or an unconfirmed MEDIUM → keep the `~/.gstack` copy and say
in one line why the repo copy was skipped. The handoff continues either way.
3. **Name the repo path** in the handoff line and any approval questions when
the repo copy exists — that's the copy the user can open and commit.
**Decision-record concision (#2000).** The doc is a decision record, not a
transcript: one bullet per decision with its why; an approach the user ruled
out DURING the session gets one line (name + rejection reason), never a
resurrected full section that re-argues the case; omit template sections that
are empty or that restate what's already settled. No page cap — extra length
must come from genuinely open questions, not template completeness.
After writing, tell the user:
**"Design doc saved to: {repo path if written, else ~/.gstack path}{when both: ' (cross-session copy in ~/.gstack)'}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
### Startup mode design doc template: