Initial commit: Clean DSS implementation
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
276
.knowledge/adrs/archived/operational/EXECUTION_CHECKLIST.md
Normal file
276
.knowledge/adrs/archived/operational/EXECUTION_CHECKLIST.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# DSS Principles Pilot - Execution Checklist
|
||||
|
||||
**Status**: All operational documents ready for customization and execution
|
||||
**Target Launch**: This week (by Friday 12/12/2025)
|
||||
**Pilot Project**: dss_sync_figma
|
||||
**Pilot Duration**: 4 weeks (Week 1-4 of December 2025)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Phase 1: Preparation (You Are Here)
|
||||
|
||||
All foundational documents have been created and are ready for customization with your team-specific details.
|
||||
|
||||
### Documents in `.knowledge/adrs/`:
|
||||
|
||||
**Core Resources** (no customization needed):
|
||||
- [x] `000-template.md` - Reusable ADR template with YAML frontmatter
|
||||
- [x] `001-use-markdown-adrs-for-dss-architecture-decisions.md` - Meta-ADR explaining the decision to use ADRs
|
||||
- [x] `README.md` - Team guide on creating and using ADRs
|
||||
|
||||
**Operational Execution Documents** (customize with [PLACEHOLDERS]):
|
||||
- [x] `SLACK_ANNOUNCEMENT_TEMPLATE.md` - Two versions (short & long) ready to post
|
||||
- [x] `KICKOFF_AGENDA.md` - 30-minute meeting script with full talking points
|
||||
- [x] `FACILITATOR_GUIDE.md` - Detailed guide for running the kickoff meeting
|
||||
- [x] `PR_TEMPLATE_UPDATE.md` - How to add DSS Principles Check to your PR template
|
||||
|
||||
**This Checklist**:
|
||||
- [x] `EXECUTION_CHECKLIST.md` - You are here
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Customization (What You Do Next)
|
||||
|
||||
Before launching the pilot, customize these documents with your team-specific details:
|
||||
|
||||
### Step 1: Prepare Team Information
|
||||
- [ ] **Identify pilot team members**: Who are the 3 people on dss_sync_figma who'll be test partners?
|
||||
- Person 1: [NAME]
|
||||
- Person 2: [NAME]
|
||||
- Person 3: [NAME]
|
||||
|
||||
- [ ] **Schedule kickoff meeting**: Pick a time this week
|
||||
- **Day**: [DAY - e.g., Thursday]
|
||||
- **Date**: [DATE - e.g., Dec 12]
|
||||
- **Time**: [TIME - e.g., 2:00 PM] (30 minutes)
|
||||
- **Location**: [LOCATION - Zoom link or conference room]
|
||||
|
||||
### Step 2: Customize Slack Announcement
|
||||
- [ ] Open `SLACK_ANNOUNCEMENT_TEMPLATE.md`
|
||||
- [ ] Fill in all [PLACEHOLDERS]:
|
||||
- `[YOUR_TEAM_SLACK_CHANNEL]` - Where to post the message
|
||||
- `[PILOT_TEAM_MEMBER_1], [PILOT_TEAM_MEMBER_2], [PILOT_TEAM_MEMBER_3]` - Actual names
|
||||
- `[DAY], [DATE], [TIME]` - Your kickoff meeting details
|
||||
- [ ] **Post to Slack**: 24-48 hours before kickoff meeting
|
||||
- Suggested: Post on Tuesday 12/10 if kickoff is Thursday 12/12
|
||||
- Use short version (150 words) unless team prefers detailed context
|
||||
- [ ] Copy-paste the post-kickoff follow-up message somewhere safe for use after meeting
|
||||
|
||||
### Step 3: Customize Kickoff Agenda
|
||||
- [ ] Open `KICKOFF_AGENDA.md`
|
||||
- [ ] Fill in [PLACEHOLDERS]:
|
||||
- `[DATE]` - Kickoff date
|
||||
- `[TIME]` - Start and end time
|
||||
- `[LOCATION]` - Zoom link or room number
|
||||
- `[PILOT TEAM NAMES]` - Your 3 pilot team members
|
||||
- `[FACILITATOR NAME]` - Person running the meeting
|
||||
- [ ] Print this or keep it open on a separate screen during the meeting (it's your reference)
|
||||
|
||||
### Step 4: Prepare Facilitator Guide
|
||||
- [ ] Open `FACILITATOR_GUIDE.md`
|
||||
- [ ] Fill in [PLACEHOLDERS]:
|
||||
- `[YOUR NAME]` - Your name as facilitator
|
||||
- `[TEAM MEMBERS]` - Names of pilot team
|
||||
- `[DATE & TIME]` - Meeting details
|
||||
- `[TEAM MEMBERS]` - (again in places)
|
||||
- [ ] **Read through the entire guide** (2,500+ lines)
|
||||
- Special focus on:
|
||||
- Pre-Meeting Checklist (line 11-25) — Complete all items before meeting
|
||||
- Section 3: The "First Pancake" (line 145-179) — This is the meeting centerpiece
|
||||
- Common Concerns table (line 218-227) — Prepare your responses
|
||||
- [ ] Set up screen share tools and test them (if running meeting remotely)
|
||||
- [ ] Have `.knowledge/adrs/` directory open and ready to screen share
|
||||
|
||||
### Step 5: Update PR Template
|
||||
- [ ] Open `PR_TEMPLATE_UPDATE.md`
|
||||
- [ ] Locate your project's PR template (likely `.github/pull_request_template.md`)
|
||||
- [ ] Copy the "DSS Principles Check" section from PR_TEMPLATE_UPDATE.md
|
||||
- [ ] Add it to your PR template **before the Checklist section**
|
||||
- [ ] Commit the change to git
|
||||
- [ ] Verify it appears on a test PR draft (optional, but recommended)
|
||||
|
||||
### Step 6: Pre-Meeting Checklist (Run Day-of or Day-Before)
|
||||
|
||||
From `FACILITATOR_GUIDE.md` lines 11-25:
|
||||
|
||||
- [ ] Review `KICKOFF_AGENDA.md` (this is your script)
|
||||
- [ ] Have `.knowledge/adrs/` open and ready to screen share
|
||||
- [ ] Open three key files in editor tabs:
|
||||
- `000-template.md` (the template)
|
||||
- `001-use-markdown-adrs-for-dss-architecture-decisions.md` (the meta-ADR)
|
||||
- Your project's updated PR template
|
||||
- [ ] Have 2-3 example decisions in mind from dss_sync_figma (for "First Pancake" fallback):
|
||||
- Example 1: [DECISION - e.g., "How will you handle Figma API token storage?"]
|
||||
- Example 2: [DECISION - e.g., "What's your caching strategy for Figma data?"]
|
||||
- Example 3: [DECISION - e.g., "Which async library will you use in Python?"]
|
||||
- [ ] Test your screen share setup (Zoom, Teams, or in-person projector)
|
||||
- [ ] Print or open the agenda for reference
|
||||
- [ ] Set a 30-minute timer (hard stop—don't let this run over)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Execution (Week 1 of Pilot)
|
||||
|
||||
### Day 1-2: Announcement
|
||||
- [ ] Post customized Slack announcement to team channel
|
||||
- Tag the pilot team members to notify them
|
||||
- Include link to `.knowledge/adrs/README.md`
|
||||
|
||||
### Day 2-3: Pre-Meeting Prep
|
||||
- [ ] Send meeting invite to pilot team with:
|
||||
- Date/time/location
|
||||
- Zoom link (if remote)
|
||||
- Calendar note: "30-minute kickoff for ADR pilot — we'll write your first ADR together"
|
||||
- [ ] Complete "Pre-Meeting Checklist" (above)
|
||||
- [ ] Mentally prepare your talking points
|
||||
|
||||
### Day 3-4: Kickoff Meeting
|
||||
- [ ] Run the 30-minute kickoff meeting using `KICKOFF_AGENDA.md` + `FACILITATOR_GUIDE.md`
|
||||
- Section 1: The "Why" (5 min)
|
||||
- Section 2: The "How" (10 min) — Live demo
|
||||
- Section 3: The "First Pancake" (10 min) — Write ADR together
|
||||
- Section 4: The "Ask" & Next Steps (5 min)
|
||||
- [ ] Capture the "First Pancake" ADR (save as `002-[title].md` if consensus reached)
|
||||
- [ ] Note any concerns or questions raised
|
||||
|
||||
### Day 4-5: Post-Meeting Followup
|
||||
- [ ] Send post-meeting Slack message (template in `SLACK_ANNOUNCEMENT_TEMPLATE.md`, lines 98-114)
|
||||
- Recap what you covered
|
||||
- Remind about next steps (create 1-3 ADRs)
|
||||
- Offer to answer questions
|
||||
- [ ] Create calendar invites for:
|
||||
- Week 2-3 check-ins (informal, async or 15-min sync)
|
||||
- Week 4 retrospective (30 minutes)
|
||||
- [ ] Add pilot team to optional Slack thread or workspace for async updates
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Piloting (Weeks 2-4)
|
||||
|
||||
### Weeks 2-3: ADR Creation
|
||||
- [ ] Pilot team creates 1-3 ADRs for significant dss_sync_figma decisions
|
||||
- They use `000-template.md` as reference
|
||||
- They link ADRs in PRs using updated PR template
|
||||
- [ ] **Facilitator check-in** (informal):
|
||||
- Week 2: Brief message asking "How's it going? Any friction?"
|
||||
- Week 3: Follow-up if there were concerns
|
||||
|
||||
### Week 4: Retrospective
|
||||
- [ ] Schedule 30-minute retrospective with pilot team
|
||||
- [ ] Use retrospective questions:
|
||||
- ✅ What worked? Did ADRs help capture decisions?
|
||||
- ❌ What didn't work? Did it feel burdensome?
|
||||
- 🔄 What should change before we roll this out broader?
|
||||
- 💡 Would you recommend this for other teams?
|
||||
- [ ] Document feedback
|
||||
- [ ] Decide: Refine, expand, or pause the ADR approach?
|
||||
|
||||
---
|
||||
|
||||
## Critical Success Factors
|
||||
|
||||
### For the Kickoff Meeting:
|
||||
- ✅ **Live demo**: Don't just talk about templates; show them on screen
|
||||
- ✅ **"First Pancake" exercise**: Write an ADR together in real-time (10 min)
|
||||
- ✅ **Keep it brief**: Template is tiny; process is lightweight; avoid over-explaining
|
||||
- ✅ **Honest tone**: "We're experimenting together"—not "here's the new mandate"
|
||||
- ✅ **Respect their time**: 30 minutes, period. Don't run over
|
||||
|
||||
### For Adoption:
|
||||
- ✅ **Lightness**: ADRs should take 15 minutes max
|
||||
- ✅ **Clarity**: Only significant decisions (not every PR)
|
||||
- ✅ **Autonomy**: "Create 1-3 ADRs" is invitation, not requirement
|
||||
- ✅ **Feedback culture**: Gather honest feedback; be willing to adjust
|
||||
|
||||
---
|
||||
|
||||
## Contingencies
|
||||
|
||||
### If Team is Skeptical During Meeting:
|
||||
- Reference the Common Concerns table in `FACILITATOR_GUIDE.md` (lines 218-227)
|
||||
- Use concrete examples from dss_sync_figma
|
||||
- Emphasize: "We're testing this. Your honest feedback is what makes it work."
|
||||
|
||||
### If Time Runs Short:
|
||||
From `FACILITATOR_GUIDE.md` (lines 240-246):
|
||||
|
||||
Priorities (in order):
|
||||
1. **Never skip the "First Pancake"** (Section 3) — This is the proof point
|
||||
2. Cut "Show the meta-ADR" if needed — Just say "look at 001 in the repo"
|
||||
3. Keep "Why" concise — Move to the demo
|
||||
4. **End on time** — Respect their calendar
|
||||
|
||||
### If Pilot Team Doesn't Create ADRs:
|
||||
- This is valid feedback: the process might be too heavy or not solving a real problem
|
||||
- Don't force it; capture the feedback in retrospective
|
||||
- Use Week 4 retro to understand why and adjust
|
||||
|
||||
---
|
||||
|
||||
## File Location Quick Reference
|
||||
|
||||
All ADR-related files are in: **`.knowledge/adrs/`**
|
||||
|
||||
| File | Purpose | Who Reads? |
|
||||
|------|---------|-----------|
|
||||
| `000-template.md` | ADR template to copy | Pilot team (when creating ADRs) |
|
||||
| `001-use-markdown-adrs-for-dss-architecture-decisions.md` | Meta-ADR explaining why we use ADRs | Pilot team (during kickoff) |
|
||||
| `README.md` | Guide on creating & using ADRs | Anyone creating ADRs |
|
||||
| `SLACK_ANNOUNCEMENT_TEMPLATE.md` | Message to post to team | You (customize & post) |
|
||||
| `KICKOFF_AGENDA.md` | Meeting agenda + talking points | You + Facilitator (reference during meeting) |
|
||||
| `FACILITATOR_GUIDE.md` | Detailed facilitator script | Facilitator (read fully before meeting) |
|
||||
| `PR_TEMPLATE_UPDATE.md` | How to integrate ADRs into PRs | You (customize your PR template) |
|
||||
| `EXECUTION_CHECKLIST.md` | This document | You (reference as you prep) |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off Checklist
|
||||
|
||||
Before claiming you're ready to launch:
|
||||
|
||||
- [ ] All pilot team members identified and briefed
|
||||
- [ ] Kickoff meeting scheduled
|
||||
- [ ] Slack announcement customized and saved (ready to post)
|
||||
- [ ] Kickoff agenda & facilitator guide reviewed and customized
|
||||
- [ ] PR template updated and committed to git
|
||||
- [ ] Pre-meeting checklist items planned (screen share, tabs, timer, etc.)
|
||||
- [ ] Example dss_sync_figma decisions identified for "First Pancake" fallback
|
||||
- [ ] Calendar invites created for retrospective (Week 4)
|
||||
|
||||
---
|
||||
|
||||
## What Happens Next (After Pilot)
|
||||
|
||||
**Month 1 Outcome** (Week 4 Retrospective):
|
||||
- You'll have real feedback on whether ADRs are valuable
|
||||
- You'll understand what needs to change for broader adoption
|
||||
- You'll decide: refine, expand, or pivot
|
||||
|
||||
**Month 2-3** (If retrospective is positive):
|
||||
- Share learnings with broader team (tech talk with pilot team as speakers)
|
||||
- Encourage other teams to try ADRs
|
||||
- Build simple tooling (e.g., grep queries, dashboard)
|
||||
|
||||
**Year 2+**:
|
||||
- Automated ADR discovery and queries
|
||||
- Dashboards showing principle adoption
|
||||
- MCP tools that suggest decisions based on code changes
|
||||
|
||||
---
|
||||
|
||||
## Questions or Issues?
|
||||
|
||||
Refer to the relevant document:
|
||||
- **How do I run the meeting?** → `FACILITATOR_GUIDE.md`
|
||||
- **What should I tell the team?** → `SLACK_ANNOUNCEMENT_TEMPLATE.md`
|
||||
- **What's the ADR format?** → `000-template.md` or `README.md`
|
||||
- **How do I integrate with PRs?** → `PR_TEMPLATE_UPDATE.md`
|
||||
- **Why are we doing this?** → `001-use-markdown-adrs-for-dss-architecture-decisions.md`
|
||||
|
||||
---
|
||||
|
||||
**Document Status**: Ready for execution
|
||||
**Created**: 2025-12-08
|
||||
**Pilot Team**: dss_sync_figma (identified by you)
|
||||
**Target Launch**: This week
|
||||
**Next Milestone**: Kickoff meeting (30 min)
|
||||
262
.knowledge/adrs/archived/operational/FACILITATOR_GUIDE.md
Normal file
262
.knowledge/adrs/archived/operational/FACILITATOR_GUIDE.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Facilitator's Guide: ADR Kickoff Meeting
|
||||
|
||||
**For**: [YOUR NAME]
|
||||
**Meeting**: DSS Principles Pilot Kickoff
|
||||
**Pilot Team**: [TEAM MEMBERS]
|
||||
**Date & Time**: [DATE & TIME]
|
||||
**Duration**: 30 minutes (strictly; this is important)
|
||||
|
||||
---
|
||||
|
||||
## Pre-Meeting Checklist (Do This Before the Meeting)
|
||||
|
||||
- [ ] Review KICKOFF_AGENDA.md (this is your script)
|
||||
- [ ] Have `.knowledge/adrs/` open and ready to screen share
|
||||
- [ ] Open the three key files in tabs:
|
||||
- `000-template.md` (the template)
|
||||
- `001-use-markdown-adrs-for-dss-architecture-decisions.md` (the meta-ADR)
|
||||
- [Your project's current PR template, if you have one—or show the example below]
|
||||
- [ ] Have a decision from `dss_sync_figma` in mind that you can use as the "First Pancake" example if the team struggles to identify one
|
||||
- Example 1: "How will you handle Figma API token storage locally vs. securely?"
|
||||
- Example 2: "What's your strategy for caching Figma data between syncs?"
|
||||
- Example 3: "Which async library will you use in Python?"
|
||||
- [ ] Test your screen share setup (Zoom, Teams, or in-person projector)
|
||||
- [ ] Print or open the agenda for reference
|
||||
- [ ] Set a 30-minute timer (hard stop; don't let this run over)
|
||||
|
||||
---
|
||||
|
||||
## During the Meeting
|
||||
|
||||
### Arrival & Opening (1 minute)
|
||||
|
||||
**What You Say**:
|
||||
> "Thanks everyone for taking the time. We've got 30 minutes, and I want to make sure we use it well. Quick housekeeping: [mention if there will be recording, etc.]. Let's dig in."
|
||||
|
||||
**What You're Doing**: Set a professional but relaxed tone. This is not a lecture.
|
||||
|
||||
---
|
||||
|
||||
### Section 1: The "Why" (5 minutes)
|
||||
|
||||
**Talking Points** (choose what feels natural; don't read verbatim):
|
||||
|
||||
1. **Acknowledge them**: "Thanks for being our partners in this pilot. We chose you because you're building something complex with real decisions to make. Your feedback is what makes this work."
|
||||
|
||||
2. **Share a relatable pain point**: Pick one from below (or use your own):
|
||||
- "Remember when we debated [specific past decision]? The reasoning lived in Slack, and now nobody remembers why we chose that way."
|
||||
- "We've all stared at six-month-old code and thought, 'Why did we do it this way?' Git shows you what changed, but not why."
|
||||
- "New team members join and ask, 'Why are we using this library instead of that one?' and the answer is just... lost."
|
||||
|
||||
3. **State the hypothesis clearly**:
|
||||
> "Our hypothesis is that capturing these decisions in a lightweight, in-repo format will help us move faster, reduce ambiguity, and actually live our principles instead of just talking about them."
|
||||
|
||||
4. **Set the tone**:
|
||||
> "Success here isn't that you love everything about it. Success is getting your honest feedback: Is this helpful, or is it just noise?"
|
||||
|
||||
**Timing**: Aim for exactly 5 minutes. Don't dwell here; move to the demo.
|
||||
|
||||
**If They Ask** during this section:
|
||||
- *"Does this mean we have to do this for every decision?"* → "No, we'll clarify scope in a second. Just the big ones."
|
||||
- *"Is this mandatory?"* → "Right now it's a pilot. We're testing it. Your feedback will tell us if it becomes mandatory."
|
||||
|
||||
---
|
||||
|
||||
### Section 2: The "How" (10 minutes)
|
||||
|
||||
**IMPORTANT**: This is a live demo. Showing is infinitely more powerful than telling. Do the screen share.
|
||||
|
||||
**Timing Breakdown**:
|
||||
- Show the directory: 1 min
|
||||
- Show the template: 2 min
|
||||
- Show the meta-ADR: 3 min
|
||||
- Show PR integration: 2 min
|
||||
- Clarify scope: 2 min
|
||||
|
||||
**What to do**:
|
||||
|
||||
**1. Show the directory (1 min)**
|
||||
```bash
|
||||
Navigate to .knowledge/adrs/ and show the file listing
|
||||
```
|
||||
**What you say**:
|
||||
> "All ADRs live right here, in the same repo as the code. They're version-controlled, reviewed in PRs, and easy to search."
|
||||
|
||||
**2. Show the template (2 min)**
|
||||
|
||||
Open `.knowledge/adrs/000-template.md`
|
||||
|
||||
**What you say**:
|
||||
> "Here's the entire template. Just Markdown with a little metadata at the top. The goal is conciseness, not a novel. You'll spend maybe 15 minutes writing one of these."
|
||||
|
||||
Point out:
|
||||
- **ID & Title**: "Sequential number so we can reference it. 'ADR-003' in a comment means everyone knows what we're talking about."
|
||||
- **Status**: "This field keeps our decisions current. Starts as 'Proposed,' becomes 'Accepted' when there's consensus, and can be marked 'Deprecated' if we change direction. This matters because old decisions stay in the repo but don't confuse people."
|
||||
- **Principles**: "We link back to PRINCIPLES.md. Makes sure we're actually living our principles, not just talking about them."
|
||||
- **Related**: "Links to docs, other ADRs, PRs. This is how we start building a knowledge graph over time."
|
||||
|
||||
**Don't dwell**: You're not explaining every field. The template speaks for itself. Move on.
|
||||
|
||||
**3. Show the meta-ADR (3 min)**
|
||||
|
||||
Open `.knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md`
|
||||
|
||||
**What you say**:
|
||||
> "This is the ADR we wrote about the decision to use ADRs. See? It's the same format. We're dogfooding this to make sure it actually works."
|
||||
|
||||
Scroll through it. Point out:
|
||||
- **Context**: "We needed a way to capture decision rationale that didn't require external tools or setup."
|
||||
- **Decision**: "Use Markdown files with YAML frontmatter. No database, no special tooling. Just text files."
|
||||
- **Consequences**: "Look—even our own decision has trade-offs. Positive: it's lightweight and git-friendly. Negative: someone has to remember to create them. We're aware of that."
|
||||
- **Status**: "This one is 'Accepted.' It's in effect now."
|
||||
|
||||
**Why show this?** It proves you believe in the process. You're using it too.
|
||||
|
||||
**4. Show PR integration (2 min)**
|
||||
|
||||
Show the updated PR template (see below). Specifically, highlight the "DSS Principles Check" section:
|
||||
|
||||
```markdown
|
||||
### DSS Principles Check
|
||||
|
||||
- **ADR Link**: If this PR implements a decision, link it here. (e.g., `Implements ADR-003`)
|
||||
- **Principle Alignment**: Which principles does this support? Explain briefly.
|
||||
```
|
||||
|
||||
**What you say**:
|
||||
> "When you open a PR that implements an ADR, you'll add a couple of lines here. That's the connection between the decision and the code. It's not overhead; it's part of how you already work."
|
||||
|
||||
**5. Clarify scope (2 min)**
|
||||
|
||||
**What you say**:
|
||||
> "Now, let's be clear: not every technical decision needs an ADR. Use this for decisions that:
|
||||
> - Impact multiple parts of the system
|
||||
> - Have interesting trade-offs or alternatives
|
||||
> - Will be referenced in future decisions
|
||||
> - Need their rationale captured for people who come after you
|
||||
>
|
||||
> Bug fixes, naming choices, small refactors—use code comments instead. ADRs are for the big stuff."
|
||||
|
||||
**If they ask**:
|
||||
- *"How do I know if something is 'big stuff'?"* → "Good question. In the retro, we can clarify this together. For now, ask yourself: Will someone in 6 months ask, 'Why did we do it that way?' If yes, it's worth an ADR."
|
||||
|
||||
---
|
||||
|
||||
### Section 3: The "First Pancake" (10 minutes)
|
||||
|
||||
**This is the core of the meeting. It turns theory into practice and builds confidence.**
|
||||
|
||||
**Setup**:
|
||||
> "Let's do this right now. We'll write an ADR for `dss_sync_figma` together. What's a significant decision you've just made or are in the middle of deciding? Examples might be: How will you handle Figma tokens locally? What's your caching strategy? Which async library will you use?"
|
||||
|
||||
**Listen**. Let them pick a decision. If they hesitate, offer your pre-prepared example(s).
|
||||
|
||||
**Once they've chosen**:
|
||||
|
||||
1. **You share your screen** (tech lead can do this if they prefer, but you control the typing)
|
||||
2. **Copy the template**:
|
||||
- Open the template file
|
||||
- Duplicate it with a name: `002-[short-title].md`
|
||||
- Show that you're doing this in real-time in the editor or file manager
|
||||
|
||||
3. **Fill it out together**:
|
||||
- You type. They talk. They're the expert; you're the scribe.
|
||||
- **YAML frontmatter**: Fill in ID, title, date, author(s), status ("Proposed" or "Accepted"), principles
|
||||
- **Context**: "What's the problem we're solving? What constraints are we working under?"
|
||||
- **Decision**: "What did we decide to do and why?"
|
||||
- **Consequences**: "What are the positive and negative implications?"
|
||||
- **Don't aim for perfection**: The goal is speed and proof of concept. 10 minutes is fine.
|
||||
|
||||
4. **Save the file**:
|
||||
- Commit to git (or just show it saved in the editor if you're not in a git client)
|
||||
- "That's it. One file, one PR link in a few weeks, and we've captured the rationale."
|
||||
|
||||
**Why this works**: It's real. It's fast. It's not scary. It proves the process doesn't require specialists or heavy tooling.
|
||||
|
||||
**If they get stuck**: Help them along. "What was the main constraint?" "What would you have done differently if you didn't have that constraint?" → These questions unlock the thinking.
|
||||
|
||||
**Timing**: Aim for 8-9 minutes, leaving 1-2 min buffer. If you're running long, skip perfection; just show "you get the idea."
|
||||
|
||||
---
|
||||
|
||||
### Section 4: The "Ask" & Next Steps (5 minutes)
|
||||
|
||||
**What you say**:
|
||||
> "That's the core loop. When you face a big decision: Spend 15 minutes capturing the 'why' and you're done. Over the next 3-4 weeks, we're asking you to create 1-3 more ADRs like that for `dss_sync_figma`."
|
||||
|
||||
**The Ask**:
|
||||
- Create 1-3 ADRs over the next month for significant decisions
|
||||
- Link them in PRs using the PR template
|
||||
- Give honest feedback in the retrospective
|
||||
|
||||
**The Support**:
|
||||
- "I'll check in informally. If you feel friction, tell me. We want to learn from that."
|
||||
- "Questions right now? Ask them. You're not alone in this."
|
||||
|
||||
**The Follow-up**:
|
||||
- "In about 4 weeks, we'll do a 30-minute retrospective to get all your feedback."
|
||||
- "At that point, we decide: Is this valuable? Do we refine it? Do we expand it to other teams?"
|
||||
|
||||
**Open the floor**:
|
||||
> "Any immediate questions or concerns?"
|
||||
|
||||
**Listen. Don't interrupt. Address concerns directly.**
|
||||
|
||||
If there are no questions, that's fine too. Say:
|
||||
> "Great. Let's start, and I'll reach out in a week to see how it's going. Thanks for being our test pilots on this."
|
||||
|
||||
---
|
||||
|
||||
## Post-Meeting (5 minutes after meeting ends)
|
||||
|
||||
- [ ] Send the follow-up Slack message (template provided)
|
||||
- [ ] Create a calendar invite for the retrospective (Week 4)
|
||||
- [ ] Add the pilot team to an (optional) Slack thread or thread for async updates
|
||||
|
||||
---
|
||||
|
||||
## Common Concerns & How to Respond
|
||||
|
||||
| Concern | Your Response |
|
||||
|---------|--|
|
||||
| "This feels like extra bureaucracy." | "I get that. That's why we're testing it. If it feels like overhead with no benefit, we'll adjust. This isn't a mandate; it's an experiment." |
|
||||
| "Do we have to do this for everything?" | "No. Just the significant decisions. We'll refine the criteria together based on your feedback." |
|
||||
| "What if we don't want to do this?" | "Then we learn that this process doesn't work for your team. Honest feedback is valuable. The goal isn't to force a process; it's to find what helps." |
|
||||
| "Can't we just use Confluence / Notion / etc.?" | "Maybe! But those require setup, are outside the repo, and are harder to keep in sync with code. We wanted something version-controlled and friction-free to start. If Markdown ADRs don't work, we can revisit." |
|
||||
| "This sounds good, but will it actually get used?" | "That's what we're testing. You're going to tell us. That's why we picked you." |
|
||||
|
||||
---
|
||||
|
||||
## Success Looks Like
|
||||
|
||||
✅ Team feels confident they can create an ADR
|
||||
✅ Team leaves with a concrete example (the one you wrote together)
|
||||
✅ At least one person says, "Oh, I see why this matters"
|
||||
✅ No one is dreading the next 4 weeks
|
||||
✅ You got honest feedback or concerns (even better—now you know what to address)
|
||||
|
||||
---
|
||||
|
||||
## If the Meeting Runs Long
|
||||
|
||||
Priorities (in order):
|
||||
1. Never skip the "First Pancake" (Section 3)
|
||||
2. Cut "Show the meta-ADR" if needed (just say "look at 001 in the repo")
|
||||
3. Keep "Why" concise; move to the demo
|
||||
4. End on time; respect their calendar
|
||||
|
||||
---
|
||||
|
||||
## Notes for You
|
||||
|
||||
- **Be confident but humble**: You're not mandating. You're inviting feedback.
|
||||
- **Listen more than talk**: Their skepticism is a gift. Lean into it.
|
||||
- **Use real examples**: Abstract explanations don't stick. Concrete examples do.
|
||||
- **Show, don't tell**: The demo and the live write are the proof points.
|
||||
- **Acknowledge uncertainty**: "I don't know" is better than "trust me." Say "We'll figure it out together."
|
||||
|
||||
---
|
||||
|
||||
**You've got this. You're not asking them to change their world; you're asking them to spend 15 minutes capturing decisions they're already making. That's a small ask with real upside.**
|
||||
|
||||
Good luck! 🚀
|
||||
180
.knowledge/adrs/archived/operational/KICKOFF_AGENDA.md
Normal file
180
.knowledge/adrs/archived/operational/KICKOFF_AGENDA.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# DSS Principles Pilot - Kickoff Meeting Agenda
|
||||
|
||||
**Date**: [DATE - THIS WEEK, e.g., Thursday Dec 12]
|
||||
**Time**: [TIME - 30 minutes, e.g., 2:00 PM - 2:30 PM]
|
||||
**Location**: [LOCATION - Zoom link or conference room]
|
||||
**Attendees**: [PILOT TEAM NAMES], [FACILITATOR NAME]
|
||||
|
||||
---
|
||||
|
||||
## Meeting Objective
|
||||
|
||||
Align the pilot team on the lightweight ADR (Architecture Decision Record) process, demonstrate its simplicity, and collaboratively write your first ADR to build confidence and momentum.
|
||||
|
||||
**This is NOT**: A mandate. A heavy process. Bureaucracy.
|
||||
**This IS**: An experiment to help us capture "why" decisions are made. Your honest feedback on whether it's valuable is the goal.
|
||||
|
||||
---
|
||||
|
||||
## Agenda (30 minutes)
|
||||
|
||||
### 1. The "Why" (5 minutes)
|
||||
|
||||
**Goal**: Frame the experiment and acknowledge their role as partners.
|
||||
|
||||
**Key Points**:
|
||||
- "Thanks for being our partners in this pilot. Your feedback is what makes this work."
|
||||
- **The Problem**: We've all asked, "Why did we do it this way?" Git history tells you *what* changed, but not *why*.
|
||||
- **The Hypothesis**: A lightweight, in-repo method for capturing decision rationale will help us move faster, reduce ambiguity, and make our principles real (not just a document).
|
||||
- **Success Criteria**: Not that you love everything about it—success is getting your honest, critical feedback. Is this helpful or just noise?
|
||||
|
||||
**Talking Points**:
|
||||
- Reference a recent past decision from the team: "Remember when we debated [example decision]? That rationale lived in Slack and now it's lost. We want to capture that."
|
||||
- Emphasize the lightness: "This is not a heavyweight process. It's 15 minutes to document a decision. That's it."
|
||||
|
||||
---
|
||||
|
||||
### 2. The "How" (10 minutes)
|
||||
|
||||
**Goal**: Demonstrate the tools are simple and unintimidating.
|
||||
|
||||
**Activity**: Live screen share. Show, don't just tell.
|
||||
|
||||
1. **Show the directory** (1 min)
|
||||
- Navigate to `.knowledge/adrs/`
|
||||
- "Everything lives right here, next to the code it relates to."
|
||||
|
||||
2. **Show the template** (2 min)
|
||||
- Open `000-template.md`
|
||||
- "This is the entire template. It's just Markdown with metadata at the top."
|
||||
- Briefly explain:
|
||||
- `status`: Keeps decisions current (Proposed → Accepted → Deprecated or Superseded)
|
||||
- `principles`: Connects the decision back to our core principles (strengthens adoption)
|
||||
- `related`: Links to docs, other ADRs, and PRs (builds the knowledge graph)
|
||||
|
||||
3. **Show the meta-ADR** (3 min)
|
||||
- Open `001-use-markdown-adrs-for-dss-architecture-decisions.md`
|
||||
- "We're dogfooding this. Here's the ADR we wrote for the decision to use ADRs. As you can see, it's short and to the point."
|
||||
- Highlight the sections: Context, Decision, Consequences
|
||||
|
||||
4. **Show the PR integration** (2 min)
|
||||
- "When you implement a decision, your PR will have a new section asking you to link the ADR. One line. That's it."
|
||||
- Show the updated PR template (section below)
|
||||
- "This connects the decision to the code."
|
||||
- Emphasize: "The process is not in the way; it's integrated into how you already work."
|
||||
|
||||
5. **Clarify scope** (2 min)
|
||||
- "Not every technical decision needs an ADR. Use this for significant decisions:"
|
||||
- Impact multiple components
|
||||
- Have trade-offs or alternatives
|
||||
- Will be referenced in future decisions
|
||||
- Need rationale captured for future developers
|
||||
- "Bug fixes, naming decisions, small refactors—those don't need ADRs. Use code comments instead."
|
||||
|
||||
---
|
||||
|
||||
### 3. The "First Pancake" (10 minutes)
|
||||
|
||||
**Goal**: Write an ADR together to prove the process is lightweight and approachable.
|
||||
|
||||
This is the most critical part of the meeting. It transforms understanding into confidence.
|
||||
|
||||
**Setup**:
|
||||
- "Let's do this right now. What's a foundational decision you're making on `dss_sync_figma` right now or have just settled on?"
|
||||
- Prompt examples if needed:
|
||||
- "How will you handle Figma API authentication? Store tokens locally or remotely?"
|
||||
- "What's your caching strategy for Figma data between runs?"
|
||||
- "What's the architecture for syncing Figma changes back to the project?"
|
||||
- "Which Python library will you use for async operations?"
|
||||
|
||||
**Execution**:
|
||||
1. Someone shares their screen (you or the tech lead)
|
||||
2. Copy `000-template.md` to `002-[decision-title].md` (show this in real-time)
|
||||
3. Fill it out collaboratively:
|
||||
- You type, pilot team provides the content
|
||||
- Aim for ~10 minutes total
|
||||
- **Don't aim for perfection**—the goal is to prove it's not intimidating
|
||||
- Get to "Accepted" status if there's consensus; otherwise "Proposed" is fine
|
||||
4. Save and show: "That's it. One file, 10 minutes, decision captured."
|
||||
|
||||
**During this exercise, demonstrate**:
|
||||
- YAML is easy (just copy the block, change the values)
|
||||
- Markdown is familiar (everyone writes it)
|
||||
- "Consequences" are often the most valuable part (forces you to think through trade-offs)
|
||||
|
||||
---
|
||||
|
||||
### 4. The "Ask" & Next Steps (5 minutes)
|
||||
|
||||
**Goal**: Set clear expectations for the pilot period and establish check-in cadence.
|
||||
|
||||
**Key Points**:
|
||||
|
||||
1. **The Ask**:
|
||||
- "Over the next 3-4 weeks, create 1-3 more ADRs for the most significant decisions on `dss_sync_figma`."
|
||||
- "A good rule of thumb: If a decision has long-term consequences, isn't easily reversible, or had interesting trade-offs, it's a good candidate."
|
||||
- "Link them from your PRs using the PR template: 'Implements ADR-NNN'"
|
||||
|
||||
2. **The Support**:
|
||||
- "I'll check in informally to see how it's going. If you feel any friction, let me know immediately. We want to learn from that."
|
||||
- "Ask questions. You're not alone in this—we're figuring it out together."
|
||||
|
||||
3. **The Follow-up**:
|
||||
- "We'll schedule a 30-minute retrospective in about 4 weeks to get all your feedback."
|
||||
- "At that point, we decide: Is this valuable? Do we refine it? Do we expand it to other teams?"
|
||||
|
||||
4. **Open the floor**:
|
||||
- "Any immediate questions, concerns, or thoughts?"
|
||||
- Listen. Address concerns directly. Be honest if you don't know something.
|
||||
|
||||
---
|
||||
|
||||
## Success Signals (What You're Looking For)
|
||||
|
||||
- ✅ Team creates 1-3 ADRs during the pilot
|
||||
- ✅ No major complaints about the process being burdensome
|
||||
- ✅ At least one person says, "Oh, I see why this matters"
|
||||
- ✅ Team links ADRs in PRs without being asked twice
|
||||
- ✅ Honest feedback in the retrospective (positive or negative)
|
||||
|
||||
## Red Flags (If You See These, Adjust)
|
||||
|
||||
- ❌ "This feels like extra bureaucracy" → Emphasize lightness; show template is only 15 min
|
||||
- ❌ "I don't know what counts as a significant decision" → Provide 1-2 concrete examples from their project
|
||||
- ❌ "Do we have to do this?" → No, it's a pilot. But we're counting on your feedback to make it better
|
||||
|
||||
---
|
||||
|
||||
## Notes for Facilitator
|
||||
|
||||
- **Be confident but humble**: You're not selling a policy; you're piloting an experiment together.
|
||||
- **Listen more than you talk**: Their skepticism and honest feedback are golden. Encourage it.
|
||||
- **Don't over-explain**: The template and example speak for themselves.
|
||||
- **Use time wisely**: The "First Pancake" exercise is worth the time; if you run short elsewhere, cut context. The live writing is the proof point.
|
||||
- **End on invitation, not mandate**: "We're excited to see what you learn. Let's reconvene in 4 weeks."
|
||||
|
||||
---
|
||||
|
||||
## Post-Meeting
|
||||
|
||||
Send a follow-up message to the pilot team:
|
||||
```
|
||||
Great kickoff! Here's what we covered:
|
||||
|
||||
• ADR template: .knowledge/adrs/000-template.md
|
||||
• The "why" behind ADRs: .knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md
|
||||
• Questions? Check: .knowledge/adrs/README.md
|
||||
|
||||
Next steps:
|
||||
1. Create 1-3 ADRs over the next month for significant dss_sync_figma decisions
|
||||
2. Link them in PRs (see PR template update)
|
||||
3. Give us feedback in the retro (Week 4)
|
||||
|
||||
Thanks for being our pilot team. Your honest feedback is what makes this work. 🚀
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Prepared for**: DSS Principles Pilot Program
|
||||
**Pilot Project**: dss_sync_figma
|
||||
**Week 1 of 4**
|
||||
252
.knowledge/adrs/archived/operational/PR_TEMPLATE_UPDATE.md
Normal file
252
.knowledge/adrs/archived/operational/PR_TEMPLATE_UPDATE.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# PR Template Update: DSS Principles Check
|
||||
|
||||
This document shows how to integrate the Architecture Decision Records (ADRs) into your existing pull request workflow.
|
||||
|
||||
**Effort**: 2 minutes to add to existing PR template
|
||||
**Impact**: Connects code changes to architectural decisions and principles
|
||||
|
||||
---
|
||||
|
||||
## Current PR Template (Example)
|
||||
|
||||
If your project doesn't have a PR template, start with this structure:
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief summary of what this PR does.
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Breaking change
|
||||
- [ ] Documentation update
|
||||
|
||||
## Related Issues
|
||||
Closes #[issue number]
|
||||
|
||||
## Testing
|
||||
How to verify this works.
|
||||
|
||||
## Screenshots (if applicable)
|
||||
Helpful for UI changes.
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Self-reviewed my own code
|
||||
- [ ] Tests pass locally
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Where to Add the DSS Principles Check
|
||||
|
||||
**Add this section just before the Checklist** (at the end, right before closing the template):
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: If this PR implements a decision from `.knowledge/adrs/`, link it here.
|
||||
Example: `Implements ADR-003: Use SQLite for Local Caching`
|
||||
|
||||
- **Principle Alignment**: Which DSS principles does this work advance? Explain briefly.
|
||||
Example: `Supports Single Source of Truth by centralizing token storage; supports Knowledge Persistence by documenting the caching strategy in ADR-003`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Updated Template (Full Example)
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief summary of what this PR does.
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Breaking change
|
||||
- [ ] Documentation update
|
||||
|
||||
## Related Issues
|
||||
Closes #[issue number]
|
||||
|
||||
## Testing
|
||||
How to verify this works.
|
||||
|
||||
## Screenshots (if applicable)
|
||||
Helpful for UI changes.
|
||||
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: If this PR implements a decision from `.knowledge/adrs/`, link it here.
|
||||
Example: `Implements ADR-003: Use SQLite for Local Caching`
|
||||
|
||||
- **Principle Alignment**: Which DSS principles does this work advance? Explain briefly.
|
||||
Example: `Supports Single Source of Truth by centralizing token storage; supports Knowledge Persistence by documenting the caching strategy in ADR-003`
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Self-reviewed my own code
|
||||
- [ ] Tests pass locally
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Update Your PR Template
|
||||
|
||||
### Option 1: GitHub PR Template File
|
||||
|
||||
If you're using GitHub, your PR template is usually at one of these locations:
|
||||
|
||||
```
|
||||
.github/pull_request_template.md
|
||||
docs/pull_request_template.md
|
||||
pull_request_template.md
|
||||
```
|
||||
|
||||
**To update**:
|
||||
1. Open the file
|
||||
2. Add the "DSS Principles Check" section before the "Checklist"
|
||||
3. Commit the change
|
||||
4. All future PRs will automatically include the new section
|
||||
|
||||
### Option 2: GitLab, Gitea, or Other Platforms
|
||||
|
||||
Check your platform's documentation for PR template location, but the process is the same: add the section to your template file.
|
||||
|
||||
### Option 3: If You Don't Have a Template Yet
|
||||
|
||||
Create a new file at `.github/pull_request_template.md` (for GitHub) with the complete template above.
|
||||
|
||||
---
|
||||
|
||||
## Good Examples vs. Anti-Patterns
|
||||
|
||||
### ✅ Good: Clear ADR Reference + Principle Alignment
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: Implements ADR-005: Use async/await for Figma API calls
|
||||
- **Principle Alignment**: Supports MCP First by using async-native patterns;
|
||||
supports Foundational Contracts by documenting API call assumptions in the ADR
|
||||
```
|
||||
|
||||
**Why this works**: Clear reference to a specific ADR; explicit connection to principles with reasoning.
|
||||
|
||||
---
|
||||
|
||||
### ✅ Good: No ADR (Because This PR Doesn't Implement a Significant Decision)
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: N/A (refactor of existing pattern)
|
||||
- **Principle Alignment**: No principle alignment—this is a straightforward refactor.
|
||||
See code comments for details.
|
||||
```
|
||||
|
||||
**Why this works**: Honest acknowledgment that not every PR needs an ADR. That's fine.
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ Anti-Pattern: Vague Principle Claims
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: ADR-001
|
||||
- **Principle Alignment**: Supports all principles
|
||||
```
|
||||
|
||||
**Problem**: Generic claim without explanation. Forces reviewer to guess what you mean.
|
||||
**Better**: Be specific. Name 1-2 principles and explain the connection.
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ Anti-Pattern: ADR Reference That Doesn't Exist
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: Implements ADR-042 (which doesn't actually exist)
|
||||
- **Principle Alignment**: Aligns with Principle X
|
||||
```
|
||||
|
||||
**Problem**: Creates confusion and breaks traceability.
|
||||
**Better**: Only reference ADRs that actually exist. If you're creating a new ADR, reference it after it's created and merged.
|
||||
|
||||
---
|
||||
|
||||
## For Code Reviewers
|
||||
|
||||
When reviewing a PR with the DSS Principles Check section:
|
||||
|
||||
1. **Verify the ADR exists**: If an ADR is referenced, confirm it's in `.knowledge/adrs/` and is relevant to the PR
|
||||
2. **Check principle alignment**: Does the PR actually support the principles claimed? If vague, ask for clarification
|
||||
3. **Allow flexibility**: Not every PR needs an ADR. Small bug fixes and refactors don't require principle alignment statements
|
||||
4. **Encourage good ADRs**: If a PR involves a significant decision but no ADR exists, ask: "Should we create an ADR for this decision?"
|
||||
|
||||
---
|
||||
|
||||
## Implementation Timeline
|
||||
|
||||
**Week 1 (Kickoff Week)**:
|
||||
- [ ] Update your PR template file with the "DSS Principles Check" section
|
||||
- [ ] Commit the change to git
|
||||
- [ ] Mention the update in the kickoff meeting
|
||||
|
||||
**Weeks 2-3 (Pilot Phase)**:
|
||||
- [ ] Pilot team creates 1-3 ADRs
|
||||
- [ ] PRs implementing those decisions link the ADR in this section
|
||||
- [ ] Reviewers validate the connections
|
||||
|
||||
**Week 4 (Retrospective)**:
|
||||
- [ ] Gather feedback: Was the PR template addition helpful or burdensome?
|
||||
- [ ] Adjust if needed (e.g., move section, simplify language, add more examples)
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Do I have to fill in the DSS Principles Check for every PR?**
|
||||
A: No. Only PRs that implement a significant decision (with an ADR) need the ADR Link. The Principle Alignment field is optional for small PRs.
|
||||
|
||||
**Q: What if I'm not sure if my PR needs an ADR?**
|
||||
A: Ask yourself: "Will someone in 6 months ask, 'Why did we make this choice?'" If yes, it probably warrants an ADR. When in doubt, ask during code review.
|
||||
|
||||
**Q: Can I reference an ADR that's still in "Proposed" status?**
|
||||
A: Yes. "Proposed" means it's being considered but not yet finalized. Once there's consensus, it moves to "Accepted." Referencing a "Proposed" ADR is fine; it just means the decision isn't final yet.
|
||||
|
||||
**Q: What if someone disagrees with the ADR I'm implementing?**
|
||||
A: That's what code review is for. If there's a concern about the decision itself (not just the implementation), the ADR should be revisited. This is healthy.
|
||||
|
||||
**Q: Should the ADR be created before the PR, or as part of it?**
|
||||
A: Ideally, before the PR. The ADR documents the *decision*, and the PR implements it. But if you're still finalizing the decision during the PR, you can create the ADR in the PR and reference it. Flexibility is fine during the pilot.
|
||||
|
||||
---
|
||||
|
||||
## Template Customization Checklist
|
||||
|
||||
Before finalizing your PR template:
|
||||
|
||||
- [ ] Check your current PR template location (`.github/pull_request_template.md` or equivalent)
|
||||
- [ ] Copy the "DSS Principles Check" section from above
|
||||
- [ ] Insert it before the "Checklist" section (or at the end if no checklist)
|
||||
- [ ] Test it by opening a draft PR and confirming the section appears
|
||||
- [ ] Mention the change during the kickoff meeting so the team knows what to expect
|
||||
|
||||
---
|
||||
|
||||
## Connection to Other Documents
|
||||
|
||||
- **ADR Template**: `.knowledge/adrs/000-template.md`
|
||||
- **ADR README**: `.knowledge/adrs/README.md`
|
||||
- **PRINCIPLES.md**: `/docs/01_core/PRINCIPLES.md` (reference for principle names)
|
||||
- **Kickoff Agenda**: `.knowledge/adrs/KICKOFF_AGENDA.md` (mentions PR integration during demo)
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready to customize and commit
|
||||
**Pilot Project**: dss_sync_figma
|
||||
**Created**: 2025-12-08
|
||||
**Next Action**: Add to your platform's PR template and commit
|
||||
81
.knowledge/adrs/archived/operational/README.md
Normal file
81
.knowledge/adrs/archived/operational/README.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# Archived Operational Documents
|
||||
|
||||
This directory contains detailed operational documents from the ADR pilot program kickoff.
|
||||
|
||||
**These files are reference-only and have been archived to keep the main working directory lean.**
|
||||
|
||||
---
|
||||
|
||||
## What's Here
|
||||
|
||||
| File | Purpose | Used When |
|
||||
|------|---------|-----------|
|
||||
| `SLACK_ANNOUNCEMENT_TEMPLATE.md` | Message to announce pilot to team | Before kickoff meeting (post 24-48 hours before) |
|
||||
| `KICKOFF_AGENDA.md` | 30-minute meeting agenda with talking points | During kickoff meeting (facilitator reference) |
|
||||
| `FACILITATOR_GUIDE.md` | Comprehensive guide for running the kickoff | Before/during kickoff (facilitator reads fully) |
|
||||
| `PR_TEMPLATE_UPDATE.md` | How to integrate ADRs into PR template | Before/during pilot (update your PR template) |
|
||||
| `EXECUTION_CHECKLIST.md` | Phase-by-phase checklist for launch | During pilot prep/execution |
|
||||
|
||||
---
|
||||
|
||||
## Quick Access
|
||||
|
||||
**If you're running a kickoff meeting** → Start with `FACILITATOR_GUIDE.md`
|
||||
|
||||
**If you're announcing the pilot** → Use `SLACK_ANNOUNCEMENT_TEMPLATE.md`
|
||||
|
||||
**If you're setting up the process** → Use `EXECUTION_CHECKLIST.md` and `PR_TEMPLATE_UPDATE.md`
|
||||
|
||||
**If you need a detailed agenda** → See `KICKOFF_AGENDA.md`
|
||||
|
||||
---
|
||||
|
||||
## Why These Are Archived
|
||||
|
||||
These documents are:
|
||||
- ✅ Comprehensive and detailed
|
||||
- ✅ Important for initial setup
|
||||
- ❌ Not needed day-to-day after pilot launch
|
||||
- ❌ Would clutter the main working directory
|
||||
|
||||
By archiving them, we keep `.knowledge/adrs/` lean (5 core files) while preserving all detail for reference.
|
||||
|
||||
---
|
||||
|
||||
## How to Use
|
||||
|
||||
All files are still fully accessible:
|
||||
|
||||
```bash
|
||||
# View a specific file
|
||||
cat archived/operational/FACILITATOR_GUIDE.md
|
||||
|
||||
# Search within archived docs
|
||||
grep -r "First Pancake" archived/operational/
|
||||
|
||||
# Copy to working directory if needed
|
||||
cp archived/operational/KICKOFF_AGENDA.md ../
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
These documents were created as part of the DSS Core Principles pilot program (December 2025).
|
||||
|
||||
- **Pilot Project**: dss_sync_figma
|
||||
- **Pilot Team**: [Your team members]
|
||||
- **Duration**: 4 weeks (Weeks 1-4 of December)
|
||||
- **Goal**: Test Architecture Decision Records (ADRs) as a lightweight process for capturing architectural decisions
|
||||
|
||||
For ongoing ADR work, use:
|
||||
- `.knowledge/adrs/000-template.md` — Create new ADRs
|
||||
- `.knowledge/adrs/README.md` — Guide for creating ADRs
|
||||
- `.knowledge/adrs/PRINCIPLES_CORE_REFERENCE.md` — Quick principle lookup
|
||||
- `.knowledge/adrs/ADR_KNOWLEDGE_MAP.md` — How decisions trace back to principles
|
||||
|
||||
---
|
||||
|
||||
**Status**: Archived (reference-only)
|
||||
**Created**: 2025-12-08
|
||||
**Owner**: DSS Core Principles Initiative
|
||||
@@ -0,0 +1,118 @@
|
||||
# Slack Announcement Template
|
||||
|
||||
Copy this message and post to [YOUR_TEAM_SLACK_CHANNEL] when ready to launch the pilot.
|
||||
|
||||
Replace [PLACEHOLDERS] with your team-specific details.
|
||||
|
||||
---
|
||||
|
||||
## Message
|
||||
|
||||
> 🎯 **DSS Principles Pilot: Architecture Decision Records**
|
||||
>
|
||||
> Hey team! We're running a 4-week pilot to strengthen our DSS principles adoption—and we want [PILOT_TEAM_MEMBER_1], [PILOT_TEAM_MEMBER_2], and [PILOT_TEAM_MEMBER_3] to be our partners in testing it.
|
||||
>
|
||||
> **The Experiment**
|
||||
> We're using lightweight "Architecture Decision Records" (ADRs) to capture the rationale behind significant decisions we make. This helps us:
|
||||
> - 📝 Capture "why" while it's fresh (not reconstruct from git history months later)
|
||||
> - 🧅 Onboard new people with context, not just code
|
||||
> - 💡 Make our core principles real, not just a document
|
||||
>
|
||||
> **The Pilot Team**
|
||||
> This starts with the `dss_sync_figma` project. [PILOT_TEAM_NAMES], we're kicking off a 30-min sync on **[DAY], [DATE], [TIME]** to show how this works and get your feedback.
|
||||
>
|
||||
> **Why You?**
|
||||
> You're building something complex right now with interesting trade-offs. Perfect for piloting this process. We want your **honest feedback**—if this feels valuable, great. If it feels like noise, tell us that too.
|
||||
>
|
||||
> **Learn More**
|
||||
> Check out `.knowledge/adrs/README.md` for the full context and how this works.
|
||||
>
|
||||
> Questions? Drop them below or in the kickoff meeting.
|
||||
>
|
||||
> Let's go! 🚀
|
||||
|
||||
---
|
||||
|
||||
## Customization Checklist
|
||||
|
||||
- [ ] Replace `[YOUR_TEAM_SLACK_CHANNEL]` with actual channel name
|
||||
- [ ] Replace `[PILOT_TEAM_MEMBER_1], [PILOT_TEAM_MEMBER_2], [PILOT_TEAM_MEMBER_3]` with actual names
|
||||
- [ ] Replace `[DAY]` with day of week (Thursday, Friday, etc.)
|
||||
- [ ] Replace `[DATE]` with date (Dec 12, etc.)
|
||||
- [ ] Replace `[TIME]` with meeting time (2:00 PM, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Timing
|
||||
|
||||
Post this message **24-48 hours before the kickoff meeting** to give team time to:
|
||||
- Read the README
|
||||
- Ask questions
|
||||
- Mentally prepare
|
||||
|
||||
## Alternative (Longer Version)
|
||||
|
||||
If your team prefers more context, use this expanded version:
|
||||
|
||||
> 🎯 **DSS Principles Pilot: Let's Try Something New**
|
||||
>
|
||||
> We've spent the last month defining DSS's core principles—the "why" behind every decision we make. Now the real work begins: **bringing those principles to life in how we actually work.**
|
||||
>
|
||||
> **The Challenge**
|
||||
> Principles are only as good as their adoption. And one of our biggest challenges is that decision rationale gets lost. You write code today, and six months later, a new team member asks, "Why did we do it this way?" Git history says *what* changed, but not *why*. That context is in Slack, in commit messages, or just in your head. It's lost.
|
||||
>
|
||||
> **The Experiment**
|
||||
> We're testing a lightweight process: **Architecture Decision Records (ADRs)**. When we make a significant decision, we spend 15 minutes capturing:
|
||||
> - What is the decision?
|
||||
> - Why did we choose it?
|
||||
> - What alternatives did we consider and reject?
|
||||
> - What are the consequences?
|
||||
>
|
||||
> That's it. One file. Done.
|
||||
>
|
||||
> **The Pilot Team**
|
||||
> [PILOT_TEAM_NAMES], you're building `dss_sync_figma` right now, and that project has *exactly* the kind of architectural decisions this is designed for. We're asking you to be our test pilots.
|
||||
>
|
||||
> **What We're NOT Asking**
|
||||
> - Don't create ADRs for every decision (just the big, consequential ones)
|
||||
> - Don't spend hours on documentation (15 mins, max)
|
||||
> - Don't adopt new tools or learn new syntax (it's just Markdown)
|
||||
>
|
||||
> **What We ARE Asking**
|
||||
> - Create 1-3 ADRs over the next month for the biggest decisions
|
||||
> - Give us honest feedback: Does this help? Or is it just bureaucracy?
|
||||
> - Help us understand what works and what doesn't
|
||||
>
|
||||
> **Kickoff Meeting**
|
||||
> [DAY], [DATE], [TIME] – 30 minutes
|
||||
> We'll show you the template (it's tiny), write your first ADR together, and answer questions.
|
||||
>
|
||||
> **Learn More**
|
||||
> - `.knowledge/adrs/README.md` – Full overview
|
||||
> - `.knowledge/adrs/001-...md` – The meta-ADR explaining why we chose this approach
|
||||
>
|
||||
> Thanks for being our partners in this. Your feedback is what makes it work. 🚀
|
||||
|
||||
---
|
||||
|
||||
## Post-Kickoff Follow-up (Optional)
|
||||
|
||||
After the kickoff meeting, consider sending this short note:
|
||||
|
||||
> **ADR Kickoff Recap**
|
||||
>
|
||||
> Thanks everyone for the great kickoff! Here's what to do next:
|
||||
>
|
||||
> 📍 **Create ADRs** for your top 2-3 `dss_sync_figma` decisions over the next month
|
||||
> 📝 **Template**: Copy `.knowledge/adrs/000-template.md`
|
||||
> 🔗 **Link in PRs**: Add to the "DSS Principles Check" section
|
||||
> 💬 **Questions**: Post in thread or grab me directly
|
||||
>
|
||||
> Check-ins: I'll reach out around week 2-3 to see how it's going.
|
||||
> Retro: We'll do a 30-minute retrospective in Week 4 to gather your feedback.
|
||||
>
|
||||
> Let's see if this helps us move faster. 🎯
|
||||
|
||||
---
|
||||
|
||||
**Ready to send?** Replace the placeholders, copy, and paste to Slack!
|
||||
Reference in New Issue
Block a user