From 61d82dc3c0d81d367ab1377b4a47fbe9845def99 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Thu, 19 Mar 2026 09:21:01 -0400 Subject: [PATCH] feat(discuss-phase): auto-generate DISCUSSION-LOG.md for audit trail (#1209) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Generate {phase_num}-DISCUSSION-LOG.md alongside CONTEXT.md during discuss-phase sessions - Log captures all options presented per gray area (not just the selected one), user's choice, notes, Claude's discretion items, and deferred ideas - File is explicitly marked as audit-only — not for agent consumption - Add discussion-log.md template with format specification - Track Q&A data accumulation instruction in discuss_areas step - Commit discussion log alongside CONTEXT.md in same git commit - Add regression tests for workflow reference and template existence --- get-shit-done/templates/discussion-log.md | 63 +++++++++++++++++++++++ get-shit-done/workflows/discuss-phase.md | 60 ++++++++++++++++++++- tests/agent-frontmatter.test.cjs | 31 +++++++++++ 3 files changed, 152 insertions(+), 2 deletions(-) create mode 100644 get-shit-done/templates/discussion-log.md diff --git a/get-shit-done/templates/discussion-log.md b/get-shit-done/templates/discussion-log.md new file mode 100644 index 000000000..37cd86692 --- /dev/null +++ b/get-shit-done/templates/discussion-log.md @@ -0,0 +1,63 @@ +# Discussion Log Template + +Template for `.planning/phases/XX-name/{phase_num}-DISCUSSION-LOG.md` — audit trail of discuss-phase Q&A sessions. + +**Purpose:** Software audit trail for decision-making. Captures all options considered, not just the selected one. Separate from CONTEXT.md which is the implementation artifact consumed by downstream agents. + +**NOT for LLM consumption.** This file should never be referenced in `` blocks or agent prompts. + +## Format + +```markdown +# Phase [X]: [Name] - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** [ISO date] +**Phase:** [phase number]-[phase name] +**Areas discussed:** [comma-separated list] + +--- + +## [Area 1 Name] + +| Option | Description | Selected | +|--------|-------------|----------| +| [Option 1] | [Brief description] | | +| [Option 2] | [Brief description] | ✓ | +| [Option 3] | [Brief description] | | + +**User's choice:** [Selected option or verbatim free-text response] +**Notes:** [Any clarifications or rationale provided during discussion] + +--- + +## [Area 2 Name] + +... + +--- + +## Claude's Discretion + +[Areas delegated to Claude's judgment — list what was deferred and why] + +## Deferred Ideas + +[Ideas mentioned but not in scope for this phase] + +--- + +*Phase: XX-name* +*Discussion log generated: [date]* +``` + +## Rules + +- Generated automatically at end of every discuss-phase session +- Includes ALL options considered, not just the selected one +- Includes user's freeform notes and clarifications +- Clearly marked as audit-only, not an implementation artifact +- Does NOT interfere with CONTEXT.md generation or downstream agent behavior +- Committed alongside CONTEXT.md in the same git commit diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index b0da511c3..be37d214f 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/get-shit-done/workflows/discuss-phase.md @@ -603,11 +603,23 @@ Back to [current area]: [return to current question]" ``` Track deferred ideas internally. + +**Track discussion log data internally:** +For each question asked, accumulate: +- Area name +- All options presented (label + description) +- Which option the user selected (or their free-text response) +- Any follow-up notes or clarifications the user provided +This data is used to generate DISCUSSION-LOG.md in the `write_context` step. Create CONTEXT.md capturing decisions made. +**Also generate DISCUSSION-LOG.md** — a full audit trail of the discuss-phase Q&A. +This file is for human reference only (software audits, compliance reviews). It is NOT +consumed by downstream agents (researcher, planner, executor). + **Find or create phase directory:** Use values from init: `phase_dir`, `phase_slug`, `padded_phase`. @@ -762,10 +774,54 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md -Commit phase context (uses `commit_docs` from init internally): +**Write DISCUSSION-LOG.md before committing:** + +**File location:** `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md` + +```markdown +# Phase [X]: [Name] - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** [ISO date] +**Phase:** [phase number]-[phase name] +**Areas discussed:** [comma-separated list] + +--- + +[For each gray area discussed:] + +## [Area Name] + +| Option | Description | Selected | +|--------|-------------|----------| +| [Option 1] | [Description from AskUserQuestion] | | +| [Option 2] | [Description] | ✓ | +| [Option 3] | [Description] | | + +**User's choice:** [Selected option or free-text response] +**Notes:** [Any clarifications, follow-up context, or rationale the user provided] + +--- + +[Repeat for each area] + +## Claude's Discretion + +[List areas where user said "you decide" or deferred to Claude] + +## Deferred Ideas + +[Ideas mentioned during discussion that were noted for future phases] +``` + +Write file. + +Commit phase context and discussion log: ```bash -node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" +node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md" ``` Confirm: "Committed: docs(${padded_phase}): capture phase context" diff --git a/tests/agent-frontmatter.test.cjs b/tests/agent-frontmatter.test.cjs index 5308f4fad..a5b4f6412 100644 --- a/tests/agent-frontmatter.test.cjs +++ b/tests/agent-frontmatter.test.cjs @@ -181,3 +181,34 @@ describe('AGENT: required frontmatter fields', () => { }); } }); + +// ─── Discussion Log ────────────────────────────────────────────────────────── + +describe('DISCUSS: discussion log generation', () => { + test('discuss-phase workflow references DISCUSSION-LOG.md generation', () => { + const content = fs.readFileSync( + path.join(WORKFLOWS_DIR, 'discuss-phase.md'), 'utf-8' + ); + assert.ok( + content.includes('DISCUSSION-LOG.md'), + 'discuss-phase must reference DISCUSSION-LOG.md generation' + ); + assert.ok( + content.includes('Audit trail only'), + 'discuss-phase must mark discussion log as audit-only' + ); + }); + + test('discussion-log template exists', () => { + const templatePath = path.join(__dirname, '..', 'get-shit-done', 'templates', 'discussion-log.md'); + assert.ok( + fs.existsSync(templatePath), + 'discussion-log.md template must exist' + ); + const content = fs.readFileSync(templatePath, 'utf-8'); + assert.ok( + content.includes('Do not use as input to planning'), + 'template must contain audit-only notice' + ); + }); +});