Skip to content

docs: adopt IBM Design Thinking governance #302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
flyingrobots merged 1 commit into from
Mar 25, 2026
Merged

docs: adopt IBM Design Thinking governance #302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

- Code standards and contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
- Documentation map and canonical docs: [docs/README.md](docs/README.md)
- Product frame: [docs/design/git-mind.md](docs/design/git-mind.md)
- Planning governance: [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
Comment on lines +7 to +8
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Same critical dependency issue as CLAUDE.md.

Lines 7-8 add cross-references to docs/design/git-mind.md and docs/adr/ADR-0005.md, identical to CLAUDE.md:7-8. AGENTS.md is the operational orders for Codex (another agent), while CLAUDE.md is for Claude.

The same critical issue applies: ADR-0005.md is not in this PR's review scope, but this file establishes it as the canonical governance reference.

See CLAUDE.md:7-8 for the full analysis and verification script.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 7 - 8, AGENTS.md currently adds a canonical
governance link to docs/adr/ADR-0005.md (and a product frame link to
docs/design/git-mind.md) but ADR-0005.md is not part of this PR; update
AGENTS.md to avoid declaring ADR-0005.md as the canonical governance within this
change by either removing the direct ADR-0005.md link, replacing it with a
non-authoritative note (e.g., "see ADR-0005.md (external/under-review)"), or
pointing to an in-scope governance document; specifically edit the lines
referencing docs/adr/ADR-0005.md and docs/design/git-mind.md in AGENTS.md to
reflect that ADR-0005.md is not included in this PR and should not be treated as
authoritative until reviewed.

- CLI/user reference: [GUIDE.md](GUIDE.md)

## FORBIDDEN ACTIONS
Expand All @@ -23,6 +25,9 @@

## REQUIRED BEHAVIOR

- **YOU MUST** use IBM Design Thinking when framing substantial product work
- **YOU MUST** identify the sponsor user, job to be done, and relevant Hill(s) when planning
- **YOU MUST** use Playbacks to judge whether work actually moved a Hill
Comment on lines +28 to +30
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Same ambiguity and enforceability issues as CLAUDE.md.

Lines 28-30 add REQUIRED BEHAVIOR mandates identical to CLAUDE.md:28-30:

  • "substantial product work" is undefined (line 28)
  • "use Playbacks to judge" is difficult for an agent to unilaterally execute (line 30)

See CLAUDE.md:28-30 for the full analysis and suggested fix.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 28 - 30, The three "YOU MUST" mandates introducing
"IBM Design Thinking", "identify the sponsor user, job to be done, and relevant
Hill(s)", and "use Playbacks to judge whether work actually moved a Hill" are
ambiguous and not enforceable by an agent; change these lines to remove hard
"YOU MUST" enforcement and either (a) define "substantial product work" and what
counts as a Playback, or (b) convert them to guidance/requirements that delegate
judgement to a human sponsor. Specifically, replace the three mandates with
clarified language such as: 1) "For substantial product work (defined as changes
that affect >X users or alter core flows), prefer IBM Design Thinking when
framing work"; 2) "Document the sponsor user, job to be done, and relevant
Hill(s) for major initiatives"; and 3) "Use Playbacks or an equivalent
human-validated review to assess Hill movement (agents should flag candidates
for Playback and escalate to the sponsor for judgement)"; update the quoted
phrases ("substantial product work", "use Playbacks") so they have definitions
or explicitly require human validation.

- **YOU MUST** tag all memories saved to your memory banks with at least `#git-mind`
- **YOU MUST** include the POSIX timestamp (via `$(date +%s)`) in memory file names
- **YOU MUST** document significant decisions or events
Expand All @@ -46,9 +51,14 @@
### 2.1. PLAN THE JOB

1. Before starting, use sequential thinking to make a plan
2. Explain your plan to the user and await approval
3. Commit your approved plan to your memory banks
4. **Create a feature branch** — `git checkout -b feat/<topic>` — before writing any code
2. Frame the plan in IBM Design Thinking terms:
- sponsor user
- job to be done
- relevant Hill(s) or supporting lane
- playback evidence
3. Explain your plan to the user and await approval
4. Commit your approved plan to your memory banks
5. **Create a feature branch** — `git checkout -b feat/<topic>` — before writing any code

### 2.2. DO THE JOB

Expand All @@ -75,6 +85,7 @@ A briefing covering:
- Current tasks and situation understanding
- Relevant stats, files, issues, PRs
- Intel the user can use to make decisions
- Sponsor user / Hill / playback framing when relevant
- Options and recommendations, then await orders

## 4. DEVLOGs
Expand Down
17 changes: 14 additions & 3 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

- Code standards and contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
- Documentation map and canonical docs: [docs/README.md](docs/README.md)
- Product frame: [docs/design/git-mind.md](docs/design/git-mind.md)
- Planning governance: [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
- CLI/user reference: [GUIDE.md](GUIDE.md)

## FORBIDDEN ACTIONS
Expand All @@ -23,6 +25,9 @@

## REQUIRED BEHAVIOR

- **YOU MUST** use IBM Design Thinking when framing substantial product work
- **YOU MUST** identify the sponsor user, job to be done, and relevant Hill(s) when planning
- **YOU MUST** use Playbacks to judge whether work actually moved a Hill
Comment on lines +28 to +30
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Define "substantial product work" and clarify the Playback mandate.

Line 28 requires using IBM Design Thinking "when framing substantial product work," but "substantial" is undefined. This creates an ambiguity gap:

  • Does fixing a typo in docs require IBM Design Thinking framing?
  • Does adding a single function to an existing module require it?
  • Where is the threshold?

Line 30 mandates "use Playbacks to judge whether work actually moved a Hill," but Playbacks are typically collaborative review sessions involving human judgment. An autonomous agent cannot unilaterally execute a Playback. Consider rephrasing to clarify the agent's actual responsibility (e.g., "prepare Playback evidence" or "document Playback outcomes").

📋 Suggested clarification 
-- **YOU MUST** use IBM Design Thinking when framing substantial product work
+- **YOU MUST** use IBM Design Thinking when framing product work that affects Hills, adds features, or changes user-facing behavior
-- **YOU MUST** use Playbacks to judge whether work actually moved a Hill
+- **YOU MUST** prepare Playback evidence to demonstrate whether work moved a Hill
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 28 - 30, The CLAUDE.md mandates are ambiguous:
explicitly define what qualifies as "substantial product work" and reword the
Playback requirement so an autonomous agent's responsibilities are clear; update
the phrase "when framing substantial product work" to include a short threshold
(e.g., scope, estimated effort, or impact criteria such as >1 week of effort,
>NLOC, cross-team impact, or new customer-facing features) and change "use
Playbacks to judge whether work actually moved a Hill" to something actionable
for agents like "prepare Playback materials and document Playback outcomes" or
"record evidence for Playback review by stakeholders" so the policy clarifies
who runs Playbacks and what the agent must produce (refer to the exact strings
"substantial product work" and "use Playbacks to judge whether work actually
moved a Hill" to locate and replace).

- **YOU MUST** tag all memories saved to your memory banks with at least `#git-mind`
- **YOU MUST** include the POSIX timestamp (via `$(date +%s)`) in memory file names
- **YOU MUST** document significant decisions or events
Expand All @@ -46,9 +51,14 @@
### 2.1. PLAN THE JOB

1. Before starting, use sequential thinking to make a plan
2. Explain your plan to the user and await approval
3. Commit your approved plan to your memory banks
4. **Create a feature branch** — `git checkout -b feat/<topic>` — before writing any code
2. Frame the plan in IBM Design Thinking terms:
- sponsor user
- job to be done
- relevant Hill(s) or supporting lane
- playback evidence
3. Explain your plan to the user and await approval
4. Commit your approved plan to your memory banks
5. **Create a feature branch** — `git checkout -b feat/<topic>` — before writing any code
Comment on lines +54 to +61
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Strengthen the planning gate and clarify the speculative nature of playback evidence.

The restructured PLAN THE JOB procedure now embeds IBM Design Thinking framing as step 2 (lines 54-58) with 5 sub-bullets. Step 3 (line 59) is "Explain your plan to the user and await approval."

The gate is implicit but not emphatic. The sub-bullet formatting might give the impression that the 5 framing items are optional or advisory rather than mandatory blockers for proceeding to step 3.

Additionally, line 58 asks the agent to identify "playback evidence" before the work is done. This is inherently speculative—the agent must predict what evidence would demonstrate that the work moved a Hill. That's valuable planning discipline, but the speculative nature should be acknowledged.

🔒 Suggested strengthening 
 1. Before starting, use sequential thinking to make a plan
 2. Frame the plan in IBM Design Thinking terms:
    - sponsor user
    - job to be done
    - relevant Hill(s) or supporting lane
-   - playback evidence
-3. Explain your plan to the user and await approval
+   - playback evidence (predict what would demonstrate progress)
+3. **DO NOT PROCEED** until all 5 framing elements above are clear
+4. Explain your plan to the user and await approval
-4. Commit your approved plan to your memory banks
-5. **Create a feature branch** — `git checkout -b feat/<topic>` — before writing any code
+5. Commit your approved plan to your memory banks
+6. **Create a feature branch** — `git checkout -b feat/<topic>` — before writing any code
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 54 - 61, Update the PLAN THE JOB section so the IBM
Design Thinking framing items are enforced as a mandatory checklist (not
optional bullets) before proceeding: require the agent to complete and document
the five framing fields (sponsor user, job to be done, relevant Hill(s)/lane,
playback evidence, and any assumptions) and explicitly block step 3 ("Explain
your plan to the user and await approval") until that checklist is signed off;
change the wording for "playback evidence" to clarify it is
predictive/speculative (e.g., "expected/playback evidence (predictive — to be
validated during playback)") and add a short gate sentence that the predicted
playback evidence must be reviewed and acknowledged by the user during the
approval step.


### 2.2. DO THE JOB

Expand All @@ -75,6 +85,7 @@ A briefing covering:
- Current tasks and situation understanding
- Relevant stats, files, issues, PRs
- Intel the user can use to make decisions
- Sponsor user / Hill / playback framing when relevant
- Options and recommendations, then await orders

## 4. DEVLOGs
Expand Down
20 changes: 20 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,26 @@ Current product frame:
- current work should be judged against low-input semantic bootstrap, provenance-backed query, and living-map upkeep
- personal cognition tooling belongs in `think`, not here

## IBM Design Thinking Expectations

Git Mind officially uses IBM Design Thinking to guide product work.

Before proposing substantial product or workflow changes, identify:

- the sponsor user
- the job to be done
- the Hill this work moves, or the supporting lane it strengthens
- the playback evidence that would prove progress

Canonical planning references:

- [docs/design/git-mind.md](docs/design/git-mind.md)
- [ROADMAP.md](ROADMAP.md)
- [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)

GitHub issues are the execution backlog.
GitHub milestones are not the primary planning surface for this repository.
Comment on lines +18 to +36
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Contributor expectations are clear, but "substantial" is undefined and ADR-0005 is unverifiable.

Lines 18-36 introduce "IBM Design Thinking Expectations" for contributors. The section is well-structured and prescriptive, identifying the 4 required elements (sponsor user, job, Hill/lane, playback evidence) before proposals.

Two issues:

  1. "Substantial" is undefined (line 22): "Before proposing substantial product or workflow changes" leaves ambiguity. What threshold defines "substantial"? Does fixing a typo count? Does adding a CLI flag count? Contributors need clearer guidance.

  2. ADR-0005 dependency (line 33): The section lists ADR-0005.md as a canonical planning reference, but ADR-0005.md is not in this PR's review scope. If it doesn't exist or contradicts this guidance, contributors will be confused.

📋 Suggested clarification for "substantial" 
-Before proposing substantial product or workflow changes, identify:
+Before proposing product or workflow changes that affect user-facing behavior, add features, or impact Hills, identify:
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CONTRIBUTING.md` around lines 18 - 36, Clarify what "substantial" means in
the "IBM Design Thinking Expectations" section by adding a brief definition and
concrete examples of changes that do and do not require the full
sponsor/user/Hill/playback checklist (e.g., typo fixes, docs tweaks, small
config flags = not substantial; feature additions, API changes, workflow changes
= substantial); and fix the ADR-0005 reference by either ensuring ADR-0005.md
exists and is up-to-date or replacing it with the correct ADR or doc link (or
noting it as "see design ADRs in docs/adr/") so the canonical planning
references are verifiable.


## Prerequisites

- Node.js >= 20.0.0
Expand Down
18 changes: 18 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,23 @@ It keeps that knowledge in Git/WARP so it can be replayed, diffed, reviewed, and
`git-mind` is not a personal thought-capture tool.
That thesis now lives in `think`.

## Planning Framework

Git Mind officially uses **IBM Design Thinking** to guide product work.

That means:

- sponsor user and jobs come before architecture expansion
- Hills define the product outcomes we are trying to achieve
- Playbacks are how we decide whether recent work actually moved a Hill
- GitHub issues are the execution backlog, not the product strategy

Canonical planning sources:

- [docs/design/git-mind.md](docs/design/git-mind.md)
- [ROADMAP.md](ROADMAP.md)
- [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
Comment on lines +22 to +37
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Planning Framework is clear but inherits the same critical dependency on the phantom ADR.

Lines 22-37 articulate the Planning Framework with admirable clarity:

  • Sponsor user and jobs precede architecture expansion (line 28)
  • Hills define outcomes (line 29)
  • Playbacks judge impact (line 30)
  • GitHub issues are execution, not strategy (line 31)

However, line 37 lists docs/adr/ADR-0005.md as one of the three canonical planning sources. As flagged in CLAUDE.md, ADR-0005.md is not included in this PR for review. The README now points users to a document I cannot verify exists or is coherent.

This is the same blocker as CLAUDE.md:7-8. See that comment for the verification script.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 22 - 37, The README's "Planning Framework" section
references ADR-0005 as a canonical planning source but ADR-0005 is not included
in this PR, blocking verification; either add the missing ADR-0005 document to
the PR or remove/replace the ADR-0005 reference in the "Planning Framework"
section so the canonical sources are all verifiable, and update the README entry
accordingly to point to an included/accessible document (refer to the "Planning
Framework" header and the ADR-0005 reference when making the change).


## What Git Mind Is For

`git-mind` is for the moment when you need to answer questions like:
Expand Down Expand Up @@ -136,6 +153,7 @@ Canonical docs:
- [GUIDE.md](GUIDE.md)
- [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md)
- [ROADMAP.md](ROADMAP.md)
- [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Consistent documentation reference, but same missing file issue.

Line 156 adds docs/adr/ADR-0005.md to the Documentation list, consistent with the Planning Framework section (lines 35-37). This reinforces the cross-referencing, but the underlying issue remains: ADR-0005.md is not in this PR's review scope.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 156, The README references docs/adr/ADR-0005.md but that
ADR file is not present in this PR; either add the missing ADR file (create
docs/adr/ADR-0005.md with the planned ADR content) or remove the link from the
Documentation list to keep the repo consistent with the current PR; update the
Planning Framework cross-reference (where ADR-0005 is mentioned) accordingly so
both locations match.

- [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md)
- [docs/design/git-mind.md](docs/design/git-mind.md)
- [docs/adr/](docs/adr/)
Expand Down
14 changes: 14 additions & 0 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,9 @@ Git Mind now uses:
- Playbacks to assess whether recent work actually moved a Hill
- GitHub issues to track concrete implementation work

This is not an informal preference.
It is the repository's official planning model per [ADR-0005](docs/adr/ADR-0005.md).
Comment on lines +54 to +55
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Strong governance declaration, but the authority is unverifiable.

Lines 54-55 declare IBM Hills/Playbacks as "the repository's official planning model per ADR-0005." The wording is unambiguous and removes any wiggle room for treating this as advisory. Good governance posture.

However, once again, ADR-0005.md is not in this PR's review scope. This PR is building a governance fortress on a foundation I cannot inspect.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@ROADMAP.md` around lines 54 - 55, The ROADMAP's statement asserting "IBM
Hills/Playbacks" as "the repository's official planning model per ADR-0005" is
authoritative but references an ADR not included in this PR; either (a) soften
the wording in ROADMAP.md around the phrase "IBM Hills/Playbacks" and the
citation to ADR-0005 to make it advisory (e.g., "aligned with ADR-0005" or "per
ADR-0005 (see linked doc)"), or (b) include ADR-0005 (docs/adr/ADR-0005.md) in
this PR so the reference is verifiable; update the text accordingly and ensure
the ADR-0005 reference is accurate and present.


GitHub milestones are intentionally not the primary planning surface anymore.
The old milestone layer had drifted into theater: completed relics staying open while the real backlog lived elsewhere.

Expand All @@ -75,6 +78,17 @@ Current GitHub planning labels:
- `lane:packaging`
- `lane:ux`

## Planning Gate

Before significant work is accepted into an active Hill or supporting lane, we should be able to answer:

1. Which sponsor user does this help?
2. Which job to be done does it improve?
3. Which Hill does it move, or which supporting lane does it strengthen?
4. What playback evidence would show that this work actually helped?

If those answers are fuzzy, the work is not ready for planning commitment yet.
Comment on lines +81 to +90
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Planning Gate is a hard blocker—good—but the phrasing could be sharper.

Lines 81-90 introduce a Planning Gate with 4 mandatory questions (lines 85-88) and a clear failure condition (line 90: "If those answers are fuzzy, the work is not ready for planning commitment yet").

This is strong gate discipline. The "we should be able to answer" phrasing (line 83) is slightly softer than "we must answer," but line 90 tightens it by establishing that fuzzy answers block commitment.

Stylistic note: Lines 85-88 have repetitive sentence structure (three of four questions start with "Which"). Static analysis flagged this. It's not a functional issue, but it's mildly monotonous in a formal checklist.

✨ Optional stylistic improvement 
 1. Which sponsor user does this help?
-2. Which job to be done does it improve?
-3. Which Hill does it move, or which supporting lane does it strengthen?
+2. What job to be done does it improve?
+3. What Hill does it move, or what supporting lane does it strengthen?
 4. What playback evidence would show that this work actually helped?
🧰 Tools
🪛 LanguageTool

[style] ~87-~87: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...hich job to be done does it improve? 3. Which Hill does it move, or which supporting ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@ROADMAP.md` around lines 81 - 90, The "Planning Gate" section uses softer
phrasing ("we should be able to answer") and repetitive question starts; update
the header block so the gate is unambiguously mandatory by changing "we should
be able to answer" to "we must answer" (or equivalent) and reword the four
checklist items under the "Planning Gate" header to remove monotony—keep content
identical but vary phrasing (e.g., "Which sponsor user benefits?", "What user
job is improved?", "Which Hill or supporting lane is advanced?", "What playback
evidence will demonstrate success?") and retain the final blocking sentence ("If
those answers are fuzzy, the work is not ready for planning commitment yet") to
preserve the hard gate.


## Current Focus: Stabilize And Clarify

Status:
Expand Down
13 changes: 13 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ These describe what Git Mind is now and how work should be judged:
- [ROADMAP.md](../ROADMAP.md) — active Hills, supporting lanes, and playback cadence
- [Git Mind Product Frame](./design/git-mind.md) — IBM Design Thinking style product frame
- [Git Mind North Star](./VISION_NORTH_STAR.md) — longer-form strategic articulation
- [ADR-0005](./adr/ADR-0005.md) — official planning and governance model
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Canonical doc list grows, phantom document persists.

Line 15 adds ADR-0005 to the "Canonical Product Docs" list with the description "official planning and governance model." This is consistent with the other files in this PR.

However, ADR-0005.md itself is not included in the PR for review. This documentation map now points contributors to a governance document I cannot verify exists or is coherent.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/README.md` at line 15, The README's "Canonical Product Docs" list now
references ADR-0005 via the markdown link `[ADR-0005](./adr/ADR-0005.md)` but
ADR-0005.md is missing from the PR; either add the ADR-0005.md file to the adr/
directory (ensuring its content matches the description "official planning and
governance model") or remove the `[ADR-0005](./adr/ADR-0005.md)` entry from the
README (or replace it with a placeholder note) so the documentation map does not
point to a non-existent phantom document.


## Canonical Engineering Guardrails

Expand Down Expand Up @@ -58,5 +59,17 @@ Hills and Playbacks live in:

- [ROADMAP.md](../ROADMAP.md)
- [Git Mind Product Frame](./design/git-mind.md)
- [ADR-0005](./adr/ADR-0005.md)
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Consistent cross-referencing, same unverified dependency.

Line 62 adds ADR-0005 to the "Hills and Playbacks live in:" list, consistent with line 15 and the broader PR changes. The cross-referencing is thorough, but the underlying issue remains: ADR-0005.md is not in this PR's review scope.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/README.md` at line 62, README.md adds a link to ADR-0005 but the
ADR-0005.md file isn't included in this PR; either remove the [ADR-0005]
reference from the "Hills and Playbacks live in:" list in README.md or add the
missing ADR-0005.md document to this PR so the link resolves correctly—locate
the reference in README.md (the added line containing "ADR-0005") and either
delete or replace it, or add the ADR-0005.md file to the repo with the
appropriate content and commit.


GitHub milestones are not the primary planning system for this repository.

## Contributor Rule

When planning work, start with:

1. sponsor user
2. jobs to be done
3. Hills
4. playback evidence

Do not start with architecture breadth, an old milestone, or a flat pile of backlog items.
123 changes: 123 additions & 0 deletions docs/adr/ADR-0005.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
# ADR-0005: IBM Design Thinking Governs Product Planning

- **Status:** Accepted
- **Date:** 2026-03-24
- **Deciders:** Git Mind maintainers
- **Related:** [docs/design/git-mind.md](../design/git-mind.md), [ROADMAP.md](../../ROADMAP.md), issue #299

## Context

Git Mind reached a point where the repository had more than one planning surface:

- GitHub issues held real implementation work.
- GitHub milestones had drifted into stale theater.
- Architecture and substrate documents were competing with the product story.
- The split that produced `think` forced Git Mind to clarify its own sponsor user and product boundary.

That ambiguity created a predictable failure mode:

- work could be justified because it was technically elegant,
- because it fit an old milestone,
- or because it expanded the platform,
- without proving that it improved Git Mind's actual product promise.

Git Mind needs a planning model that keeps the team focused on the sponsor user, the product job to be done, and observable progress toward the current hill.

## Decision

Git Mind adopts **IBM Design Thinking** as its official product planning and review framework.

In this repository, that means:

1. **Sponsor user and jobs come first.**
- Work starts by identifying who the change is for and what repository-understanding job it improves.

2. **Hills define strategic outcomes.**
- Git Mind does not plan product direction primarily through GitHub milestones.
- Hills are the primary statement of what outcome the product is trying to achieve.
Comment on lines +35 to +37
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

"Hills" referenced without definition in this ADR.

Line 36 states "Hills are the primary statement of what outcome the product is trying to achieve," but the term itself isn't formally defined here. While IBM Design Thinking practitioners understand Hills as ambitious goal statements with measurable outcomes, readers unfamiliar with the framework may struggle.

Consider adding a brief inline definition or explicitly noting that Hills are defined in docs/design/git-mind.md.

📖 Proposed clarification 
 2. **Hills define strategic outcomes.**
-   - Git Mind does not plan product direction primarily through GitHub milestones.
+   - Hills (ambitious, outcome-focused goal statements defined in the product frame) are the primary statement of what outcome the product is trying to achieve.
-   - Hills are the primary statement of what outcome the product is trying to achieve.
+   - Git Mind does not plan product direction primarily through GitHub milestones.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
2. **Hills define strategic outcomes.**
- Git Mind does not plan product direction primarily through GitHub milestones.
- Hills are the primary statement of what outcome the product is trying to achieve.
2. **Hills define strategic outcomes.**
- Hills (ambitious, outcome-focused goal statements defined in the product frame) are the primary statement of what outcome the product is trying to achieve.
- Git Mind does not plan product direction primarily through GitHub milestones.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/adr/ADR-0005.md` around lines 35 - 37, ADR-0005 currently uses the term
"Hills" without defining it; update the "2. **Hills define strategic
outcomes.**" paragraph in ADR-0005 to include a one-sentence inline definition
(e.g., "Hills are ambitious, time‑bound outcome statements with measurable
indicators") and add a parenthetical pointer to the Git Mind design
documentation for full details (referencing the Git Mind design doc rather than
a full excerpt), so readers unfamiliar with the framework understand what
"Hills" means.


3. **Playbacks are required to judge progress.**
- Progress is evaluated by evidence that recent work moved a Hill, not just by counting completed tasks.

4. **GitHub issues are the execution backlog.**
- Issues remain the unit of work.
- Labels may map issues to Hills and supporting lanes.
- Milestones are optional release-management aids, not the control plane.

5. **Canonical planning artifacts must stay aligned.**
- The sponsor user, jobs, doctrine, and hill framing live in `docs/design/git-mind.md`.
- The current hill map, supporting lanes, and playback cadence live in `ROADMAP.md`.
- `README.md`, `docs/README.md`, contributor instructions, and agent instructions must point back to that model instead of inventing their own.

## Required Operating Model

### Canonical Sources

- `docs/design/git-mind.md`
- sponsor user
- jobs to be done
- product thesis
- doctrine
- playback questions

- `ROADMAP.md`
- active focus
- hill map
- supporting lanes
- playback cadence

- GitHub issues
- concrete implementation backlog

### Planning Rules

Before significant work starts, contributors and agents should be able to answer:
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Define "significant work" with precision.

Line 74 introduces the threshold "significant work" but leaves it undefined. What constitutes significant vs. trivial work? A typo fix? A documentation update? A new feature? A refactor?

Without clear boundaries, this planning gate becomes subjective and unenforceable. Either:

  1. Define "significant" with concrete criteria (e.g., "changes affecting user-facing behavior" or "PRs touching >X files"), or
  2. State explicitly that ALL work requires framing, with a documented exception process for trivial fixes.
🎯 Proposed fix: Define the threshold 
-Before significant work starts, contributors and agents should be able to answer:
+Before starting work that affects user-facing behavior or product direction, contributors and agents should be able to answer:

Or add a definition section:

 ### Planning Rules
+
+**"Significant work"** means any change that:
+- Adds or modifies user-facing features
+- Changes CLI interfaces or repository analysis behavior  
+- Requires architectural decisions
+
+Trivial fixes (typos, formatting, dead link repairs) may skip this gate but should still reference relevant planning context when available.

 Before significant work starts, contributors and agents should be able to answer:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Before significant work starts, contributors and agents should be able to answer:
Before starting work that affects user-facing behavior or product direction, contributors and agents should be able to answer:
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/adr/ADR-0005.md` at line 74, The ADR currently uses the term
"significant work" without definition; update ADR-0005 to either (A) add a
concise definition under a new "Definitions" or "Scope" paragraph that lists
concrete criteria for "significant work" (e.g., changes affecting user-facing
behavior, API/DB/schema changes, security/performance/cost impact, cross-repo or
cross-team changes, PRs touching >N files or >M lines, new external
dependencies), or (B) explicitly require that all changes must be framed but
provide a documented fast-track exception process for trivial fixes (typos,
small doc updates, single-line formatting) including who may approve exceptions;
mention the term "significant work" and the chosen thresholds/examples so
reviewers can apply the gate consistently.


1. Which sponsor user does this help?
2. Which job does it improve?
3. Which Hill does it move, or which supporting lane does it strengthen?
Comment on lines +76 to +78
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Fix repetitive sentence structure.

Lines 76-78 begin three consecutive sentences with "Which," creating monotonous rhythm. Vary the sentence structure for better readability.

✍️ Proposed rephrase 
 1. Which sponsor user does this help?
-2. Which job does it improve?
-3. Which Hill does it move, or which supporting lane does it strengthen?
+2. What job does it improve?
+3. Does it move a Hill or strengthen a supporting lane? Which one?
 4. What playback evidence would demonstrate progress?
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
1. Which sponsor user does this help?
2. Which job does it improve?
3. Which Hill does it move, or which supporting lane does it strengthen?
1. Which sponsor user does this help?
2. What job does it improve?
3. Does it move a Hill or strengthen a supporting lane? Which one?
🧰 Tools
🪛 LanguageTool

[style] ~78-~78: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... help? 2. Which job does it improve? 3. Which Hill does it move, or which supporting ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/adr/ADR-0005.md` around lines 76 - 78, The three numbered questions in
ADR-0005 all start with "Which," causing monotonous repetition; update the three
items so they vary sentence starters and tone—for example keep the first as
"Which sponsor user does this help?", change the second to "What job does it
improve?" and the third to "What Hill does it move, or which supporting lane
does it strengthen?"—or use similar rephrasings that avoid starting every line
with "Which"; edit the list entries (the three numbered questions) accordingly
to improve readability while preserving original meaning.

4. What playback evidence would demonstrate progress?

If those questions cannot be answered, the work is not yet framed well enough.

## Alternatives Rejected

### 1. GitHub milestones as the primary planning system

Rejected because milestones had already drifted away from reality and were not acting as a trustworthy control plane.

### 2. Architecture-first planning

Rejected because Git Mind had already proven it could generate technically coherent substrate work without necessarily making the product more compelling.

### 3. Backlog-only planning

Rejected because a flat list of issues does not preserve sponsor-user focus, product outcomes, or a shared definition of progress.

## Consequences

### Positive

- Product planning stays anchored to the sponsor user and real repository questions.
- Work can be judged against explicit Hills rather than vague platform ambition.
- Playbacks create a repeatable way to detect drift early.
- Documentation can be simplified around one planning model.

### Costs

- Planning requires more explicit framing discipline.
- Some technically interesting work will be deferred if it does not clearly move a Hill.
- Contributors must learn the sponsor-user/Hills/Playbacks vocabulary.

## Enforcement

This ADR should be reflected in:

- `README.md`
- `docs/README.md`
- `docs/design/git-mind.md`
- `ROADMAP.md`
- contributor instructions
- agent instructions

Comment on lines +112 to +122
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Enforcement mechanism is underspecified.

Lines 112-122 list WHERE this ADR should be reflected but provide no concrete HOW:

  1. Who enforces? Maintainers during PR review? An automated check? Periodic audit?
  2. When is compliance checked? At PR time? Quarterly review?
  3. What's the remediation process when drift is detected?
  4. Is there an escape hatch for urgent security/bug fixes that can't wait for full IBM Design Thinking framing?
  5. How is this ADR itself updated or challenged if the framework proves inadequate?

Without operational details, this "enforcement" section is aspirational rather than executable. Governance without enforcement is just suggestion.

🔧 Proposed enforcement clarifications 
 ## Enforcement

 This ADR should be reflected in:

 - `README.md`
 - `docs/README.md`
 - `docs/design/git-mind.md`
 - `ROADMAP.md`
 - contributor instructions
 - agent instructions

-If those documents drift away from this model, they should be corrected.
+### Compliance Checks
+
+- **PR Review:** Maintainers verify that PRs introducing significant work include sponsor user, job, and Hill framing in the description or linked issue.
+- **Quarterly Audit:** A maintainer reviews canonical planning documents for alignment and files issues to correct drift.
+
+### Exception Process
+
+Urgent security or bug fixes may be merged without full planning framing, but must be reconciled with Hills/Playbacks in the next planning review.
+
+### Updating This ADR
+
+If this framework proves inadequate, any maintainer may propose an ADR superseding or amending ADR-0005 through the standard ADR process.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/adr/ADR-0005.md` around lines 112 - 122, The Enforcement section in
ADR-0005.md is underspecified: update the "Enforcement" block to define concrete
mechanisms (who, when, remediation, escape hatch, and ADR-change process);
explicitly name responsible roles (e.g., Maintainers or Security Team), the
checkpoint timing (e.g., PR gate, automated CI check, quarterly audit), the
remediation workflow (e.g., create tracking issue, hotfix vs. staged
remediation, SLA), an emergency escape process for urgent fixes (temporary
exception process + post-facto ADR review), and the ADR amendment process (who
can propose changes and how to ratify them); reference the listed targets
(README.md, docs/README.md, docs/design/git-mind.md, ROADMAP.md, contributor
instructions, agent instructions) and add a line describing an automated
compliance check and a periodic review cadence so the enforcement text becomes
actionable.

If those documents drift away from this model, they should be corrected.
19 changes: 18 additions & 1 deletion docs/adr/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# Architecture Decision Records (ADRs)

This directory captures durable architecture decisions for Git Mind.
This directory captures durable architecture and governance decisions for Git Mind.

These ADRs are architecture references, not the canonical product narrative.
Some of them were written during a broader platform and bridge planning phase, but they still matter where they establish substrate or invariants that remain in force.
Some ADRs also capture repository-level planning and governance rules when those rules are intended to constrain how future work is framed.

Use ADRs for decisions that are hard to reverse, cross-cut multiple subsystems, or define platform invariants.

Expand Down Expand Up @@ -106,6 +107,22 @@ Prevents git-mind from duplicating CRDT, time-travel, observer, and provenance g

---

## [ADR-0005](./ADR-0005.md) — IBM Design Thinking Governs Product Planning
**Status:** Accepted
**Date:** 2026-03-24

### What it establishes
- IBM Design Thinking is the official planning model for Git Mind.
- Sponsor user, jobs, Hills, and Playbacks are the primary product framing tools.
- GitHub issues are the execution backlog.
- GitHub milestones are not the primary planning control plane.
- Canonical planning docs must stay aligned with that model.

### Why it matters
Prevents Git Mind from drifting back into milestone theater, architecture-first planning, or backlog-only decision making.

Comment on lines +110 to +123
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

ADR-0005 index entry is a summary, but the actual ADR is still not in this PR for review.

Lines 110-123 add an index entry for ADR-0005, summarizing its governance model:

  • IBM Design Thinking is official (line 115)
  • Sponsor user, jobs, Hills, Playbacks are primary framing tools (line 116)
  • GitHub issues are execution backlog (line 117)
  • GitHub milestones are not primary control plane (line 118)
  • Canonical planning docs must align (line 119)

This is a clear summary, but it's still just an index entry. The actual docs/adr/ADR-0005.md file is not included in this PR for review. I cannot verify:

  • That ADR-0005.md exists
  • That its full contents match this summary
  • That it provides the level of detail required for a governance ADR

This PR is updating 8 files to reference ADR-0005.md as the canonical governance source, but the source itself is invisible to this review.

See CLAUDE.md:7-8 for the verification script.

Minor formatting violations:

Static analysis (markdownlint) flags missing blank lines around the new headings (lines 110, 114, 121). These are stylistic lint violations, not functional issues, but they should be fixed to maintain markdown hygiene.

🔧 Formatting fix 
 ---
 
+## [ADR-0005](./ADR-0005.md) — IBM Design Thinking Governs Product Planning
-## [ADR-0005](./ADR-0005.md) — IBM Design Thinking Governs Product Planning
 **Status:** Accepted
 **Date:** 2026-03-24
+
-### What it establishes
+### What it establishes
 - IBM Design Thinking is the official planning model for Git Mind.
 - Sponsor user, jobs, Hills, and Playbacks are the primary product framing tools.
 - GitHub issues are the execution backlog.
 - GitHub milestones are not the primary planning control plane.
 - Canonical planning docs must stay aligned with that model.
+
-### Why it matters
+### Why it matters
 Prevents Git Mind from drifting back into milestone theater, architecture-first planning, or backlog-only decision making.
 
 ---
🧰 Tools
🪛 LanguageTool

[grammar] ~122-~122: Use a hyphen to join words.
Context: ...first planning, or backlog-only decision making. --- ## Quick Contribution Rule...

(QB_NEW_EN_HYPHEN)

🪛 markdownlint-cli2 (0.21.0)

[warning] 110-110: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

[warning] 114-114: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

[warning] 121-121: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/adr/README.md` around lines 110 - 123, The PR adds an index entry for
ADR-0005 but does not include the actual ADR content, so add the missing
ADR-0005 document (create the full ADR-0005.md with the governance details
summarized in the index) and ensure all references in the ADR index point to
that new ADR file; run the repository verification script referenced in
CLAUDE.md to validate presence/consistency. Also fix the markdownlint issues in
the ADR index README by adding the required blank lines around the new headings
(the ADR index headings and the IBM Design Thinking summary) so the file passes
static analysis.

---

## Quick Contribution Rules

- Keep ADRs concise but specific.
Expand Down
6 changes: 5 additions & 1 deletion docs/design/git-mind.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# Git Mind Product Frame

Status: draft for review
Status: canonical product frame

This document is the canonical IBM Design Thinking product frame for Git Mind.
Planning governance is defined in [ADR-0005](../adr/ADR-0005.md).
Comment on lines +3 to +6
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Status promotion is appropriate, but governance link is unverifiable.

Lines 3-6 promote this document from draft to "canonical product frame" and explicitly tie planning governance to ADR-0005.md. The status elevation is appropriate given the PR objectives, but line 6 introduces the same critical dependency on the unreviewed ADR-0005.md.

If this PR merges before ADR-0005.md is verified, users will follow the link and potentially find nothing, or find a document that contradicts the governance model described here.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/design/git-mind.md` around lines 3 - 6, The document currently promotes
"Status: canonical product frame" while linking planning governance to ADR-0005
(unverified); either remove or soften the hard link to ADR-0005 or mark ADR-0005
as pending to avoid a broken/misleading reference: update the "Status: canonical
product frame" line or the sentence referencing ADR-0005 so it reads
conditionally (e.g., "planning governance is defined in ADR-0005 (pending
verification)") or point the link to a draft/placeholder until ADR-0005 is
reviewed; ensure you edit the exact strings "Status: canonical product frame"
and the ADR-0005 reference so readers aren’t directed to an unverified doc.


## Purpose

Expand Down Expand Up @@ -258,6 +261,7 @@ Repository hygiene work on 2026-03-24 exposed four important facts:
## Recommended Operating Model

`git-mind` should no longer use GitHub milestones as its primary planning system.
That is now an accepted repository rule under [ADR-0005](../adr/ADR-0005.md), not just a temporary recommendation.
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Hardening a recommendation into a rule is good governance discipline.

Line 264 elevates the no-milestones policy from a recommendation to "an accepted repository rule under ADR-0005." This is strong, clear governance language. It removes ambiguity about whether the milestone prohibition is optional.

However, the authority cited (ADR-0005.md) is not in this PR's review scope. If ADR-0005.md doesn't actually establish this rule, the citation is hollow.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/design/git-mind.md` at line 264, The sentence that upgrades the
"no-milestones" policy to an accepted repository rule cites ADR-0005 but may be
incorrect; verify that ADR-0005 actually codifies the no-milestones rule and if
it does not, either update ADR-0005 to include that rule or remove/soften the
claim in docs/design/git-mind.md (change "an accepted repository rule under
[ADR-0005]" to reflect the true status, e.g., "a recommended policy" or point to
the correct ADR), ensuring the reference to ADR-0005 and the phrase
"no-milestones" are consistent and accurate.


Recommended split:

Expand Down
Loading