Discussing

Discussion Document Skill

Modes

This skill has two modes based on arguments:

• Create mode: /discussing "title" — creates a new discussion document
• Update mode: /discussing D001 — appends a log entry to an existing discussion

Create Mode

When argument is a title string (not a D-prefixed ID):

Step 1: Ensure folder exists

Check if .crabshell/discussion/ exists.

• Folder does not exist: Create it and create .crabshell/discussion/INDEX.md with content below.
• Folder exists but INDEX.md does NOT exist: Pre-existing files detected. Create .crabshell/discussion/backup/, move ALL existing files into it, then create INDEX.md. Report to user: "Moved N existing files to .crabshell/discussion/backup/"
• Folder exists and INDEX.md exists: Already managed. Proceed.

INDEX.md content:

# Discussion Index

| ID | Title | Status | Created | Related |
|----|-------|--------|---------|---------|

Step 2: Determine next ID

Glob .crabshell/discussion/D*.md to find existing files. Extract numeric part from filenames (e.g., D001 → 1, D012 → 12). Next ID = max + 1, zero-padded to 3 digits. If no files exist, start at 001.

Step 3: Create discussion document

Filename: .crabshell/discussion/D{NNN}-{slug}.md

• {slug} = title converted to kebab-case (non-English titles: keep as-is with hyphens for spaces)

Before asking the 3 questions below: Proactively present constraints:

1. Read .crabshell/project.md — extract ## Constraints section
2. Infer task-specific constraints from context (topic, related D/P/I, regressing cycle)
3. Present to the user:

Constraint Check:
- [Project] {each constraint from project.md}
- [Inferred] {constraints from task context, e.g., "Per P{NNN}, scope limited to X"}
Additional constraints? Silence = proceed.

4. Confirmed constraints are written to the ## Constraints section of the D document

Ask the user:

1. Intent: Why is this discussion needed? What decision is being made?
2. Context: Related files, issues, prior discussions?
3. Intent Anchor: What are the specific, measurable outcomes? (IA items) Convergence Criteria (auto-detect): Before asking, check if .crabshell/memory/regressing-state.json exists AND has active === true:

• If regressing active: DO NOT ask the user. Auto-fill measurable items derived from the IA: one criterion per IA item stating how it is verified (recorded evidence in a cycle ticket, command exit code, or numeric threshold), plus "Final Report written and D status: concluded". The host goal evaluator reads these during regressing (regressing SKILL.md Step 2.6) — every item must be checkable by reading documents or running a command; subjective wording ("no new issues found") is INVALID. Inform user: "Convergence criteria auto-applied (regressing context detected)."
• If NOT regressing: Ask: "Convergence Criteria: What observable conditions would indicate the goal is fully achieved? (For non-regressing, write 'Not applicable.')"

Then create the document:

---
type: discussion
id: D{NNN}
title: "{title}"
status: open
created: {YYYY-MM-DD}
tags: []
---

# D{NNN} - {title}

## Intent
{user's answer about intent}

## Context
{user's answer about context}

## Constraints
- [Project] {constraints from project.md}
- [Inferred] {constraints from task context}
- [User] {additional constraints from user, if any}

## Intent Anchor
- IA-1: {first intent anchor item}
- IA-2: {second intent anchor item}
(Finalized after confirmation with user)

## IA Source Mapping
| IA Item | User Statement (verbatim or near-verbatim) | Mapping Type |
|---------|---------------------------------------------|-------------|

**Unmapped check:** Every user-stated goal MUST map to at least one IA item. If any user statement has no IA mapping → HALT and ask user to confirm exclusion.
Mapping Type: `direct` (user explicitly stated) or `inferred` (derived from context, requires user confirmation)

## Convergence Criteria
{If regressing active (regressing-state.json active===true): auto-filled measurable items — one per IA item with its verification method (documented evidence, command exit, numeric threshold) + "Final Report written and D status: concluded". Must be checkable by the host goal evaluator by reading documents or running a command.
If NOT regressing: user's answer — observable conditions for "done", or "Not applicable — non-regressing discussion."}

## Discussion Log

---
### [{YYYY-MM-DD HH:MM}] Started
{Initial discussion topic or opening statement}

• Document-first rule: Create the D document using the Write tool BEFORE reporting to the user. The document creation is the primary action; the conversation confirmation is secondary.

Step 4: Update INDEX.md

Append a new row to the table in .crabshell/discussion/INDEX.md:

| [[D{NNN}-{slug}|D{NNN}]] | {title} | open | {YYYY-MM-DD} | |

Note: {slug} is the kebab-case portion of the document filename. Obtain it by globbing .crabshell/discussion/D{NNN}-*.md and extracting the basename without .md.

Step 5: Confirm to user

Tell the user: "Created D{NNN}. Discussion is open. Continue the dialogue and I'll record it."

Update Mode

When argument matches D\d{3} pattern:

Step 1: Read existing document

Read .crabshell/discussion/D{NNN}-*.md (glob to find the file). If not found, tell user and stop.

Step 2: Append log entry

Append to the end of the document:

---
### [{YYYY-MM-DD HH:MM}] {entry_type}
{content}

Where entry_type is one of:

• A summary of the discussion point (default)

• Conclusion — when a conclusion is reached

• Status change: {old} → {new} — when status changes

• Document-first rule: Append the log entry to the D document using the Edit tool FIRST. The document update is the primary action; the conversation acknowledgment is secondary.

Step 3: Update INDEX.md if status changed

If the entry includes a status change, update the status column in .crabshell/discussion/INDEX.md for this ID.

Status Transitions

• open → concluded (decision reached)
• open → abandoned (no longer relevant)

Rules

1. NEVER modify existing content in a discussion document. Only append to the Discussion Log section.
2. Timestamps use local time: [YYYY-MM-DD HH:MM]
3. INDEX.md is the only file where existing content may be modified (status column updates).
4. When the discussion leads to a plan, note in the log: "→ See [[P{NNN}-{slug}|P{NNN}]]" and update INDEX.md Related column with the same wikilink format. Obtain {slug} by globbing .crabshell/plan/P{NNN}-*.md and extracting the basename without .md. If the target document does not exist yet, use the bare ID temporarily: "→ See P{NNN}".
5. No parent transition while children incomplete: If a related P exists and is not yet done → do not transition D to concluded. Can only conclude when related plan is completed.
6. Auto-conclude: When related P becomes done, D is automatically set to concluded by ticketing cascade. No manual conclusion needed.
7. Mandatory work log: After performing any work related to this document, append a log entry to the Discussion Log section using the existing format (### [{YYYY-MM-DD HH:MM}] {entry_type}). This applies regardless of whether this skill was explicitly invoked — if the work touched or advanced this discussion's purpose, log it.
8. Orchestrator reference obligation: Orchestrator MUST reference this D document's Intent Anchor during P (planning) and T (execution) stages. IA items are read-only evaluation criteria and cannot be modified.
9. Regressing context passing: In regressing mode, this D document serves as the top-level container for all cycles. The D stays open throughout all cycles and closes with the final report. Cycle feedback (T(n) → P(n+1)) bypasses D and goes directly between T and P documents. When created for regressing mode, the Intent Anchor MUST include an item requiring '/verifying each cycle' — this anchors the verification tool check as a first-class IA requirement, not just a procedural step.
10. Scope Note: In this project, verification means closing the gap between belief and reality through observation (Predict → Execute → Compare). Evidence citations are required work product, not verbose output.
11. IA Source Mapping is mandatory for regressing mode. Every IA item must trace to a user statement. The IA Source Mapping table must be populated before proceeding to the first cycle.