From f7b2915446aff888bea1f01703b39088c1e34e67 Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 24 Mar 2026 21:48:22 -0700 Subject: [PATCH] docs: adopt IBM Design Thinking governance (#299) --- AGENTS.md | 17 +++++- CLAUDE.md | 17 +++++- CONTRIBUTING.md | 20 +++++++ README.md | 18 ++++++ ROADMAP.md | 14 +++++ docs/README.md | 13 +++++ docs/adr/ADR-0005.md | 123 ++++++++++++++++++++++++++++++++++++++++ docs/adr/README.md | 19 ++++++- docs/design/git-mind.md | 6 +- 9 files changed, 239 insertions(+), 8 deletions(-) create mode 100644 docs/adr/ADR-0005.md diff --git a/AGENTS.md b/AGENTS.md index 6f341fe..b01b744 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 @@ -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 - **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 @@ -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/` — 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/` — before writing any code ### 2.2. DO THE JOB @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index 00c6bad..326939e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 @@ -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 - **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 @@ -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/` — 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/` — before writing any code ### 2.2. DO THE JOB @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57b3337..d427732 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. + ## Prerequisites - Node.js >= 20.0.0 diff --git a/README.md b/README.md index 10f6073..9ae6e72 100644 --- a/README.md +++ b/README.md @@ -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) + ## What Git Mind Is For `git-mind` is for the moment when you need to answer questions like: @@ -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) - [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md) - [docs/design/git-mind.md](docs/design/git-mind.md) - [docs/adr/](docs/adr/) diff --git a/ROADMAP.md b/ROADMAP.md index 0bffdfb..3a50d35 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -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). + 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. @@ -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. + ## Current Focus: Stabilize And Clarify Status: diff --git a/docs/README.md b/docs/README.md index 8a70ee2..bea8e42 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 ## Canonical Engineering Guardrails @@ -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) 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. diff --git a/docs/adr/ADR-0005.md b/docs/adr/ADR-0005.md new file mode 100644 index 0000000..ee3b19f --- /dev/null +++ b/docs/adr/ADR-0005.md @@ -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. + +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: + +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? +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 + +If those documents drift away from this model, they should be corrected. diff --git a/docs/adr/README.md b/docs/adr/README.md index cde6ba4..2cd5fcb 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. @@ -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. + +--- + ## Quick Contribution Rules - Keep ADRs concise but specific. diff --git a/docs/design/git-mind.md b/docs/design/git-mind.md index 39804b7..651f02e 100644 --- a/docs/design/git-mind.md +++ b/docs/design/git-mind.md @@ -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). ## Purpose @@ -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. Recommended split: