docs: adopt IBM Design Thinking governance#302
Merged
flyingrobots merged 1 commit intomainfrom Mar 25, 2026
Merged
Conversation
Contributor
Summary by CodeRabbit
WalkthroughThis PR establishes IBM Design Thinking as Git Mind's official product planning and governance framework, introducing consistent requirements across documentation: identifying sponsor users, jobs-to-be-done, Hills, and Playback evidence before substantial work. Governance codified in new ADR-0005. Changes
Sequence Diagram(s)No diagrams applicable: changes are documentation-only with no code control flow, component interactions, or functional modifications. Estimated code review effort🎯 2 (Simple) | ⏱️ ~13 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 18
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 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.
- Around line 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.
In `@CLAUDE.md`:
- Around line 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).
- Around line 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.
In `@CONTRIBUTING.md`:
- Around line 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.
In `@docs/adr/ADR-0005.md`:
- Around line 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.
- Around line 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.
- Around line 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.
- 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.
In `@docs/adr/README.md`:
- Around line 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.
In `@docs/design/git-mind.md`:
- Around line 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.
- 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.
In `@docs/README.md`:
- 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.
- 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.
In `@README.md`:
- 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.
- Around line 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).
In `@ROADMAP.md`:
- Around line 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.
- Around line 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 361f36cd-e7d0-4910-99b7-52540e2a9a69
📒 Files selected for processing (9)
AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.mdROADMAP.mddocs/README.mddocs/adr/ADR-0005.mddocs/adr/README.mddocs/design/git-mind.md
Comment on lines
+7
to
+8
| - Product frame: [docs/design/git-mind.md](docs/design/git-mind.md) | ||
| - Planning governance: [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md) |
Contributor
There was a problem hiding this comment.
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.
Comment on lines
+28
to
+30
| - **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 |
Contributor
There was a problem hiding this comment.
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.
Comment on lines
+28
to
+30
| - **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 |
Contributor
There was a problem hiding this comment.
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).
Comment on lines
+54
to
+61
| 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 |
Contributor
There was a problem hiding this comment.
🧹 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.
Comment on lines
+18
to
+36
| ## 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. |
Contributor
There was a problem hiding this comment.
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:
-
"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.
-
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.
|
|
||
| - [ROADMAP.md](../ROADMAP.md) | ||
| - [Git Mind Product Frame](./design/git-mind.md) | ||
| - [ADR-0005](./adr/ADR-0005.md) |
Contributor
There was a problem hiding this comment.
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.
Comment on lines
+22
to
+37
| ## 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) |
Contributor
There was a problem hiding this comment.
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).
| - [GUIDE.md](GUIDE.md) | ||
| - [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md) | ||
| - [ROADMAP.md](ROADMAP.md) | ||
| - [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md) |
Contributor
There was a problem hiding this comment.
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.
Comment on lines
+54
to
+55
| This is not an informal preference. | ||
| It is the repository's official planning model per [ADR-0005](docs/adr/ADR-0005.md). |
Contributor
There was a problem hiding this comment.
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.
Comment on lines
+81
to
+90
| ## 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. |
Contributor
There was a problem hiding this comment.
🧹 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.
48 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Title
docs: adopt IBM Design Thinking governance
Summary
Problem Statement
Git Mind's product frame had been clarified, but the planning discipline itself still lived mostly as prose and recent conversation context. That left too much room for drift back toward milestone theater, architecture-first planning, or backlog-only decision making. The repository needed a durable, visible rule that makes IBM Design Thinking part of the operating model instead of an optional preference.
ADR Compliance (Required)
Relevant ADR(s)
Compliance Declaration
Exception Request (Required if deviating)
Architecture Laws Checklist (Hard Gates)
Canonical Truth & Context
--at,--observer,--trust) or deterministically defaulted.Determinism & Provenance
Artifact Hygiene
Contracts & Compatibility
Extension/Effects Safety (if applicable)
Scope Control
Backward Compatibility
Test Plan (Required)
Unit
npm test -- test/diff.test.jsIntegration
# No integration test changes; this is a docs/governance PR.Determinism
# Not applicable for this docs/governance change.Contract/Schema
# No schema changes.Policy Gates
Security / Trust Impact
Performance Impact
Observability / Debuggability
Operational Notes
npm testsuite currently exhibits pre-existing timeout flake under full-suite load; targeted reruns such asnpm test -- test/diff.test.jspass.Linked Issues / Milestones
Reviewer Quick Verdict Block (for maintainers)
MUST (Hard Gates)
SHOULD (Quality)
Verdict