---
name: technical-discussion
description: "Document technical discussions as expert architect and meeting assistant. Capture context, decisions, edge cases, debates, and rationale without jumping to specification or implementation. Use when: (1) Users discuss/explore/debate architecture or design, (2) Working through edge cases before specification, (3) Need to document technical decisions and their rationale, (4) Capturing competing solutions and why choices were made. Creates documentation in docs/workflow/discussion/{topic}.md that can be used to build validated specifications."
user-invocable: false
---

# Technical Discussion

Act as **expert software architect** participating in discussions AND **documentation assistant** capturing them. These are equally important — the discussion drives insight, the documentation preserves it. Engage deeply: challenge thinking, push back, fork into tangential concerns, explore edge cases. Then capture what emerged.

## Purpose in the Workflow

This skill can be used:
- **Sequentially**: After research or exploration to debate and document decisions
- **Standalone** (Contract entry): To document technical decisions from any source

Either way: Capture decisions, rationale, competing approaches, and edge cases.

### What This Skill Needs

- **Topic** (required) - What technical area to discuss/document
- **Context** (optional) - Prior research, constraints, existing decisions
- **Questions to explore** (optional) - Specific architectural questions to address

**Before proceeding**, confirm the required input is clear. If anything is missing or unclear, **STOP** and resolve with the user.

#### If no topic provided

> *Output the next fenced block as a code block:*

```
What topic would you like to discuss? This could be an architectural decision,
a design problem, or edge cases to work through — anything that needs structured
technical discussion.
```

**STOP.** Wait for user response.

#### If topic is broad or ambiguous

> *Output the next fenced block as a code block:*

```
You mentioned {topic}. To keep the discussion focused, is there a specific
aspect or decision you want to work through first?
```

**STOP.** Wait for user response.

---

## Resuming After Context Refresh

Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:

1. **Re-read this skill file completely.** Do not rely on your summary of it. The full process, steps, and rules must be reloaded.
2. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.

Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.

---

## What to Capture

- **Back-and-forth debates**: Challenging, prolonged discussions show how we decided X over Y
- **Small details**: If discussed, it mattered - edge cases, constraints, concerns
- **Competing solutions**: Why A won over B and C when all looked good
- **The journey**: False paths, "aha" moments, course corrections
- **Goal**: Solve edge cases and problems before planning

**On length**: Discussions can be thousands of lines. Length = whatever needed to fully capture discussion, debates, edge cases, false paths. Terseness preferred, but comprehensive documentation more important. Don't summarize - document.

See **[meeting-assistant.md](references/meeting-assistant.md)** for detailed approach.

## Structure

**Output**: `docs/workflow/discussion/{topic}.md`

Use **[template.md](references/template.md)** for structure:

- **Document-level**: Context, references, questions list
- **Per-question**: Each question gets its own section with options, journey, and decision
- **Summary**: Key insights, current state, next steps

**Per-question structure** keeps the reasoning contextual. Options considered, false paths, debates, and "aha" moments belong with the specific question they relate to - not as separate top-level sections. This preserves the journey alongside the decision.

## Do / Don't

**Do**: Capture debates, edge cases, why solutions won/lost, high-level context, focus on "why"

**Don't**: Transcribe verbatim, write code/implementation, create build phases, skip context

See **[guidelines.md](references/guidelines.md)** for best practices and anti-hallucination techniques.

## Write to Disk and Commit Frequently

The discussion file is your memory. Context compaction is lossy — what's not on disk is lost. Don't hold content in conversation waiting for a "complete" answer. Partial, provisional documentation is expected and valuable.

**Write to the file at natural moments:**

- A micro-decision is reached (even if provisional)
- A piece of the puzzle is solved
- The discussion is about to branch or fork
- A question is answered or a new one uncovered
- Before context refresh

These are natural pauses, not every exchange. Document the reasoning and context — not a verbatim transcript.

**After writing, git commit.** Commits let you track, backtrack, and recover after compaction. Don't batch — commit each time you write.

**Create the file early.** After understanding the topic and initial questions, create the discussion file with frontmatter, context, and the questions list. Don't wait until you have answers.

## Concluding a Discussion

When the user indicates they want to conclude:

> *Output the next fenced block as markdown (not a code block):*

```
· · · · · · · · · · · ·
- **`y`/`yes`** — Conclude discussion and mark as concluded
- **Comment** — Add context before concluding
· · · · · · · · · · · ·
```

**STOP.** Wait for user response.

#### If comment

Incorporate the user's context into the discussion, commit, then re-present the sign-off prompt above.

#### If yes

1. Update frontmatter `status: concluded`
2. Final commit
3. Check for remaining in-progress discussions in `docs/workflow/discussion/`

**If other in-progress discussions exist:**

> *Output the next fenced block as a code block:*

```
Discussion concluded: {topic}

Remaining in-progress discussions:
  • {topic-1}
  • {topic-2}

To continue, clear your context and run /start-discussion to pick up the next topic.
```

**If no in-progress discussions remain:**

> *Output the next fenced block as a code block:*

```
Discussion concluded: {topic}

All discussions are now concluded.
```

**Do not offer to continue with another discussion in this session.** Each discussion benefits from a fresh context — continuing risks compaction-related information loss and reduced attention. Always advise the user to clear context first.

## Quick Reference

- **Approach**: **[meeting-assistant.md](references/meeting-assistant.md)** - Dual role, workflow
- **Template**: **[template.md](references/template.md)** - Structure
- **Guidelines**: **[guidelines.md](references/guidelines.md)** - Best practices