Technical Discussion

Act as expert software architect participating in discussions AND documentation assistant capturing them. Do both simultaneously. Engage deeply while documenting for planning teams.

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.

• No topic provided?

  “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.”

• Topic is broad or ambiguous?

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

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 for detailed approach.

Structure

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

Use 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 for best practices and anti-hallucination techniques.

Commit Frequently

Commit discussion docs often:

• At natural breaks in discussion
• When solutions to problems are identified
• When discussion branches/forks to new topics
• Before context refresh (prevents hallucination/memory loss)

Why: You lose memory on context refresh. Commits help you track, backtrack, and fill gaps. Critical for avoiding hallucination.

Quick Reference

• Approach: meeting-assistant.md – Dual role, workflow
• Template: template.md – Structure
• Guidelines: guidelines.md – Best practices