dss/.knowledge/adrs/archived/operational/FACILITATOR_GUIDE.md

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)

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:

### 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! 🚀