---
name: self-improving-conversation
description: "Captures dialogue learnings, tone mismatches, escalation failures, and conversation quality issues. Logs redacted summaries to .learnings/. Optional project-scoped hooks use a narrow matcher. Promote to prompt files or extract skills only after explicit human review of a diff. Use when: (1) A user expresses frustration or confusion, (2) Tone mismatch is detected, (3) Context is lost mid-conversation, (4) Agent hallucinates, (5) User requests escalation, (6) Conversation is abandoned or rephrased repeatedly, (7) A missing conversational capability is identified."
metadata:
---

# Self-Improving Conversation Skill

Log dialogue learnings, tone issues, and conversation failures to markdown files for continuous improvement. Conversational agents can later process these into playbooks. Important patterns may be promoted to project memory after explicit human review of a diff. Optional hooks are reminder-only and project-scoped.

## First-Use Initialisation

Before logging anything, ensure the `.learnings/` directory and files exist in the project or workspace root. If any are missing, create them:

```bash
mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nTone mismatches, context losses, hallucinations, and dialogue insights captured during conversations.\n\n**Categories**: tone_mismatch | misunderstanding | escalation_failure | context_loss | sentiment_drift | hallucination\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/DIALOGUE_ISSUES.md ] || printf "# Dialogue Issues Log\n\nConversation failures, misunderstandings, tone mismatches, and escalation problems.\n\n---\n" > .learnings/DIALOGUE_ISSUES.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nConversational capabilities requested by users or identified through dialogue analysis.\n\n---\n" > .learnings/FEATURE_REQUESTS.md
```

Never overwrite existing files. This is a no-op if `.learnings/` is already initialised.

Do not log personally identifiable information, auth tokens, or private user data unless the user explicitly asks for that level of detail. Prefer short summaries or redacted excerpts over raw conversation transcripts.

If you want automatic reminders or setup assistance, use the opt-in hook workflow described in [Hook Integration](#hook-integration).

## Quick Reference

| Situation | Action |
|-----------|--------|
| User says "That's not what I meant" | Log to `.learnings/DIALOGUE_ISSUES.md` with `misunderstanding` |
| Formal response to casual user | Log to `.learnings/LEARNINGS.md` with category `tone_mismatch` |
| Lost thread in multi-turn dialogue | Log to `.learnings/LEARNINGS.md` with category `context_loss` |
| Agent states incorrect facts | Log to `.learnings/LEARNINGS.md` with category `hallucination` |
| User asks for human agent | Log to `.learnings/DIALOGUE_ISSUES.md` with `escalation_failure` |
| User sentiment drops mid-conversation | Log to `.learnings/LEARNINGS.md` with category `sentiment_drift` |
| User requests missing capability | Log to `.learnings/FEATURE_REQUESTS.md` |
| User abandons conversation | Log to `.learnings/DIALOGUE_ISSUES.md` with `abandonment` |
| Simplify/Harden recurring patterns | Log/update `.learnings/LEARNINGS.md` with `Source: simplify-and-harden` and a stable `Pattern-Key` |
| Similar to existing entry | Link with `**See Also**`, consider priority bump |
| Conversation pattern is proven | Propose a reviewed diff for `SOUL.md`, `AGENTS.md`, or `TOOLS.md`; apply only after explicit approval |

## OpenClaw Setup (Recommended)

OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.

### Installation

**Via ClawdHub (recommended):**
```bash
clawdhub install self-improving-conversation
```

**Manual:**
```bash
git clone https://github.com/jose-compu/self-improving-conversation.git ~/.openclaw/skills/self-improving-conversation
```

### Workspace Structure

OpenClaw injects these files into every session:

```
~/.openclaw/workspace/
├── AGENTS.md          # Dialogue workflows, handoff protocols, escalation chains
├── SOUL.md            # Conversational tone, personality, empathy guidelines
├── TOOLS.md           # Integration capabilities, channel-specific gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── DIALOGUE_ISSUES.md
    └── FEATURE_REQUESTS.md
```

### Create Learning Files

```bash
mkdir -p ~/.openclaw/workspace/.learnings
```

Then create the log files (or copy from `assets/`):
- `LEARNINGS.md` — tone mismatches, context losses, hallucinations, sentiment drift
- `DIALOGUE_ISSUES.md` — escalation failures, misunderstandings, abandoned conversations
- `FEATURE_REQUESTS.md` — user-requested conversational capabilities

### Promotion Targets

When learnings prove broadly applicable, promote them to workspace files:

| Learning Type | Promote To | Example |
|---------------|------------|---------|
| Conversation patterns | `SOUL.md` | "Match user's formality level within 2 exchanges" |
| Dialogue workflows | `AGENTS.md` | "Offer human handoff after 3 failed intent matches" |
| Integration gotchas | `TOOLS.md` | "Slack threads lose context after 50 messages" |

### Optional: Enable Hook

Opt-in and project-scoped. Enabling a hook persists across future sessions; skip this unless you need reminders:

```bash
cp -r hooks/openclaw ~/.openclaw/hooks/self-improving-conversation
openclaw hooks enable self-improving-conversation
```

See `references/openclaw-integration.md` for complete details.

---

## Generic Setup (Other Agents)

For Claude Code, Codex, Copilot, or other agents, create `.learnings/` in the project or workspace root:

```bash
mkdir -p .learnings
```

Create the files inline using the headers shown above. Avoid reading templates from the current repo or workspace unless you explicitly trust that path.

### Add reference to agent files AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md to remind yourself to log dialogue learnings. (This is an alternative to hook-based reminders.)

#### Self-Improving Conversation Workflow

When dialogue issues or conversation failures occur:
1. Log to `.learnings/DIALOGUE_ISSUES.md`, `LEARNINGS.md`, or `FEATURE_REQUESTS.md`
2. Review and promote broadly applicable patterns to:
   - `CLAUDE.md` - project conversation conventions
   - `AGENTS.md` - dialogue workflows and escalation protocols
   - `.github/copilot-instructions.md` - Copilot conversation context

## Logging Format

### Learning Entry

Append to `.learnings/LEARNINGS.md`:

```markdown
## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: greeting | intent_detection | response_generation | handoff | follow_up | closing

### Summary
One-line description of the conversational learning

### Details
Full context: what the user said, what the agent responded, what went wrong,
what the correct response should have been

### Suggested Action
Specific conversational improvement: tone adjustment, intent mapping, escalation rule

### Metadata
- Source: conversation | user_feedback | sentiment_analysis | dialogue_review
- Related Files: path/to/dialogue_config.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: tone.formality_mismatch | context.thread_loss (optional, for recurring-pattern tracking)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

---
```

### Dialogue Issue Entry

Append to `.learnings/DIALOGUE_ISSUES.md`:

```markdown
## [DLG-YYYYMMDD-XXX] issue_type

**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: greeting | intent_detection | response_generation | handoff | follow_up | closing

### Summary
Brief description of the dialogue failure

### Conversation Excerpt
```
User: [what the user said]
Agent: [what the agent responded]
User: [user reaction indicating failure]
```

### Root Cause
- Misidentified intent / tone mismatch / missing context / hallucination / escalation gap

### Impact
- User frustration level: low | moderate | high | critical
- Conversation outcome: resolved_late | abandoned | escalated | unresolved

### Suggested Fix
How to handle this conversation pattern in the future

### Metadata
- Reproducible: yes | no | unknown
- Channel: web | slack | api | voice
- Related Files: path/to/intent_config.ext
- See Also: DLG-20250110-001 (if recurring)

---
```

### Feature Request Entry

Append to `.learnings/FEATURE_REQUESTS.md`:

```markdown
## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 timestamp
**Priority**: medium
**Status**: pending
**Area**: greeting | intent_detection | response_generation | handoff | follow_up | closing

### Requested Capability
What conversational capability the user wanted

### User Context
Why they needed it, what dialogue scenario triggered it

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built: new intent, dialogue flow, integration, playbook

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_capability_name
- Channel: web | slack | api | voice

---
```

## ID Generation

Format: `TYPE-YYYYMMDD-XXX`
- TYPE: `LRN` (learning), `DLG` (dialogue issue), `FEAT` (feature)
- YYYYMMDD: Current date
- XXX: Sequential number or random 3 chars (e.g., `001`, `A7B`)

Examples: `LRN-20250115-001`, `DLG-20250115-A3F`, `FEAT-20250115-002`

## Resolving Entries

When an issue is fixed, update the entry:

1. Change `**Status**: pending` → `**Status**: resolved`
2. Add resolution block after Metadata:

```markdown
### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Fix Applied**: Updated intent taxonomy / added escalation rule / adjusted tone config
- **Notes**: Brief description of what was done
```

Other status values:
- `in_progress` - Actively being investigated or fixed
- `wont_fix` - Decided not to address (add reason in Resolution notes)
- `promoted` - Elevated to SOUL.md, AGENTS.md, or conversation playbook

## Promoting to Project Memory

When a conversational learning is broadly applicable (not a one-off exchange), promote it to permanent project memory.

### When to Promote

- Learning applies across multiple conversation flows
- Knowledge any conversational agent should know
- Prevents recurring dialogue failures
- Documents project-specific conversational conventions

### Promotion Targets

| Target | What Belongs There |
|--------|-------------------|
| `CLAUDE.md` | Project conversation conventions, tone rules, known user patterns |
| `AGENTS.md` | Dialogue workflows, escalation protocols, handoff procedures |
| `.github/copilot-instructions.md` | Conversation context and conventions for Copilot |
| `SOUL.md` | Conversational personality, empathy guidelines, tone rules (OpenClaw workspace) |
| `TOOLS.md` | Channel capabilities, integration limits, API quirks (OpenClaw workspace) |

### How to Promote

1. **Distill** the learning into a concise conversational rule or guideline
2. **Prepare** a minimal patch for the appropriate section in the target file (create file if needed)
3. **Show a reviewed diff and apply only after explicit user approval**
4. **Update** original entry:
   - Change `**Status**: pending` → `**Status**: promoted`
   - Add `**Promoted**: SOUL.md`, `AGENTS.md`, or target file

### Promotion Examples

**Learning**: Agent used technical jargon with a non-technical user. Three exchanges wasted.
**In SOUL.md**: `Mirror user's vocabulary level within 2 exchanges. Avoid jargon with casual users.`

**Learning**: User asked for human three times before agent escalated. User abandoned.
**In AGENTS.md**: `Initiate handoff after second "talk to human" request. Never require more than 2.`

## Recurring Pattern Detection

If logging something similar to an existing entry:

1. **Search first**: `grep -r "keyword" .learnings/`
2. **Link entries**: Add `**See Also**: DLG-20250110-001` in Metadata
3. **Bump priority** if issue keeps recurring
4. **Consider systemic fix**: Recurring conversation issues often indicate:
   - Missing intent in taxonomy (→ update intent config)
   - Tone mismatch pattern (→ promote to SOUL.md)
   - Missing escalation path (→ promote to AGENTS.md)
   - Channel-specific limitation (→ document in TOOLS.md)

## Simplify & Harden Feed

Use this workflow to ingest recurring patterns from the `simplify-and-harden` skill and turn them into durable conversational guidance.

### Ingestion Workflow

1. Read `simplify_and_harden.learning_loop.candidates` from the task summary.
2. Use `pattern_key` as the stable dedupe key.
3. Search `.learnings/LEARNINGS.md` for existing entry: `grep -n "Pattern-Key: <key>" .learnings/LEARNINGS.md`
4. If found: increment `Recurrence-Count`, update `Last-Seen`, add `See Also` links.
5. If not found: create new `LRN-...` entry with `Source: simplify-and-harden`, set `Pattern-Key`, `Recurrence-Count: 1`.

### Promotion Rule

Promote when: `Recurrence-Count >= 3`, seen across 2+ conversation flows, within 30-day window.
Targets: `SOUL.md` (tone), `AGENTS.md` (escalation), `TOOLS.md` (channel limits).
Write short prevention guidelines, not dialogue transcripts.

## Periodic Review

Review `.learnings/` at natural breakpoints:

### When to Review
- Before handling a complex dialogue flow
- After a conversation with user frustration signals
- When working on intent taxonomy or escalation rules
- Weekly during active chatbot development

### Quick Status Check
```bash
# Count pending items
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority dialogue issues
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["

# Find learnings for a specific area
grep -l "Area\*\*: intent_detection" .learnings/*.md
```

### Review Actions
- Resolve fixed dialogue issues
- Promote applicable conversational patterns
- Link related entries across flows
- Escalate recurring misunderstanding patterns

## Detection Triggers

Automatically log when you notice:

**Tone Mismatches** (→ learning with `tone_mismatch` category):
- Response formality doesn't match user's style
- Overly technical language for a casual user
- Too casual for a formal/professional context
- Emoji or humor where user expects seriousness

**Misunderstandings** (→ dialogue issue):
- "That's not what I meant"
- "No, I was asking about..."
- "You misunderstood"
- User rephrases the same question 3+ times

**Escalation Failures** (→ dialogue issue with `escalation_failure`):
- "Can I talk to a human?"
- "Let me speak to someone real"
- "I need a real person"
- "This isn't working, transfer me"

**Context Loss** (→ learning with `context_loss` category):
- Agent asks question already answered earlier
- Agent contradicts its own prior response
- Agent loses track of multi-step request
- "I already told you that"

**Sentiment Drift** (→ learning with `sentiment_drift` category):
- User starts friendly, becomes curt
- Increasing use of caps or punctuation (!!!)
- Shorter responses indicating disengagement
- Explicit frustration markers ("ugh", "come on")

**Hallucination** (→ learning with `hallucination` category):
- Agent states business hours, policies, or data that doesn't exist
- Agent references features that aren't available
- Agent fabricates conversation history
- Agent cites non-existent documentation or sources

**Feature Gaps** (→ feature request):
- "Can you also handle..."
- "I wish the bot could..."
- "Why can't you understand..."
- "Do you support [language/channel]?"

## Priority Guidelines

| Priority | When to Use |
|----------|-------------|
| `critical` | User PII exposed in conversation, security breach, data leak in dialogue |
| `high` | Repeated misunderstanding affecting core flow, escalation path broken, hallucination about critical info |
| `medium` | Tone mismatch causing friction, context loss in long conversations, sentiment drift |
| `low` | Minor phrasing improvement, edge-case intent miss, cosmetic dialogue issue |

## Area Tags

Use to filter learnings by conversation phase:

| Area | Scope |
|------|-------|
| `greeting` | Opening messages, welcome flows, channel detection |
| `intent_detection` | NLU, intent classification, entity extraction |
| `response_generation` | Reply composition, tone selection, content assembly |
| `handoff` | Escalation to human, agent transfer, channel switching |
| `follow_up` | Clarification loops, confirmation, next-step suggestions |
| `closing` | Farewell, satisfaction check, feedback collection |

## Best Practices

1. **Log immediately** — conversational context is lost quickly once the exchange moves on
2. **Include conversation excerpts** — future agents need to see the actual exchange
3. **Note the user's emotional state** — helps calibrate future tone adjustments
4. **Record the channel** — Slack, web, API, voice all have different constraints
5. **Suggest concrete dialogue fixes** — not just "improve response" but specific phrasing
6. **Track intent taxonomy gaps** — misunderstandings often mean missing intents
7. **Promote tone rules aggressively** — if in doubt, add to SOUL.md
8. **Review before complex flows** — check for known issues in similar dialogue paths

## Gitignore Options

**Keep learnings local** (per-developer):
```gitignore
.learnings/
```

This repo uses that default to avoid committing sensitive conversation logs by accident.

**Track learnings in repo** (team-wide):
Only track `.learnings/` after a human has reviewed entries for secrets, PII, and privileged content.

**Hybrid** (track templates, ignore entries):
```gitignore
.learnings/*.md
!.learnings/.gitkeep
```

## Hook Integration

Enable automatic reminders through agent hooks. This is **opt-in** — you must explicitly configure hooks.

Hooks persist across sessions once installed. Keep them **project-scoped**. Do **not** install user-level or global hooks. Never use an empty `matcher`. `PostToolUse` inspects command output in-process; do not log raw output, secrets, or transcripts.

### Quick Setup (Claude Code / Codex)

Create `.claude/settings.json` in your project:

```json
{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "dialogue|conversation|chatbot|intent|escalat|tone|hallucin",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-conversation/scripts/activator.sh"
      }]
    }]
  }
}
```

This injects a dialogue learning evaluation reminder after matching prompts (~50-100 tokens overhead).

### Advanced Setup (With Error Detection)

Add `PostToolUse` hook alongside activator for automated dialogue failure detection from command output. See `references/hooks-setup.md` for the full JSON configuration.

### Available Hook Scripts

| Script | Hook Type | Purpose |
|--------|-----------|---------|
| `scripts/activator.sh` | UserPromptSubmit | Reminds to evaluate dialogue learnings after tasks |
| `scripts/error-detector.sh` | PostToolUse (Bash) | Triggers on conversation error patterns |

See `references/hooks-setup.md` for detailed configuration and troubleshooting.

## Automatic Skill Extraction

Extracted skills are untrusted until a human reviews the generated `SKILL.md`. Do not keep or publish an extracted skill without explicit user approval.

When a conversational learning is valuable enough to become a reusable skill, extract it using the provided helper.

### Skill Extraction Criteria

A learning qualifies for skill extraction when ANY of these apply:

| Criterion | Description |
|-----------|-------------|
| **Recurring** | Has `See Also` links to 2+ similar dialogue issues |
| **Verified** | Status is `resolved` with working conversational fix |
| **Non-obvious** | Required actual dialogue analysis to discover the pattern |
| **Broadly applicable** | Not project-specific; useful across chatbot implementations |
| **User-flagged** | User says "save this as a skill" or similar |

### Extraction Workflow

1. **Identify candidate**: Dialogue learning meets extraction criteria
2. **Run helper** (or create manually):
   ```bash
   ./skills/self-improving-conversation/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improving-conversation/scripts/extract-skill.sh skill-name
   ```
3. **Customize SKILL.md**: Fill in template with conversational learning content
4. **Update learning**: Set status to `promoted_to_skill`, add `Skill-Path`
5. **Verify**: Read skill in fresh session to ensure it's self-contained

### Extraction Detection Triggers

**In conversation:** "Save this dialogue pattern", "We keep getting this wrong", "This would help other chatbots"

**In learning entries:** Multiple `See Also` links, high priority + resolved, `tone_mismatch` or `escalation_failure` with broad applicability

### Skill Quality Gates

- [ ] Pattern tested across multiple dialogue flows
- [ ] Description clear without original conversation context
- [ ] Dialogue examples anonymized (no PII)
- [ ] Follows skill naming conventions (lowercase, hyphens)

## Multi-Agent Support

This skill works across different AI agents with agent-specific activation.

### Claude Code

**Activation**: Hooks (UserPromptSubmit, PostToolUse)
**Setup**: `.claude/settings.json` with hook configuration
**Detection**: Automatic via hook scripts

### Codex CLI

**Activation**: Hooks (same pattern as Claude Code)
**Setup**: `.codex/settings.json` with hook configuration
**Detection**: Automatic via hook scripts

### GitHub Copilot

**Activation**: Manual (no hook support)
**Setup**: Add to `.github/copilot-instructions.md`:

```markdown
## Conversation Self-Improvement

After handling dialogue interactions, consider logging to `.learnings/`:
1. Tone mismatches, misunderstandings, escalation failures
2. Link related entries with See Also
3. Promote proven conversational patterns to skills

Ask in chat: "Should I log this dialogue issue?"
```

**Detection**: Manual review at session end

### OpenClaw

**Activation**: Workspace injection + inter-agent messaging
**Setup**: See "OpenClaw Setup" section above
**Detection**: Via session tools and workspace files

### Agent-Agnostic Guidance

Regardless of agent, apply conversation self-improvement when you:

1. **Detect tone mismatch** — your formality doesn't match the user's
2. **Lose context** — you forgot something the user already said
3. **Hallucinate** — you stated something factually incorrect
4. **Fail to escalate** — user wanted a human and didn't get one
5. **Miss intent** — user had to rephrase multiple times

### Copilot Chat Integration

Quick prompts for Copilot users:
- "Log this dialogue issue"
- "Create a skill from this conversation pattern"
- "Check .learnings/ for related dialogue issues"

## Stackability Contract (Standalone + Multi-Skill)

This skill is standalone-compatible and stackable with other self-improving skills.

### Namespaced Logging (recommended for 2+ skills)
- Namespace for this skill: `.learnings/conversation/`
- Keep current standalone behavior if you prefer flat files.
- Optional shared index for all skills: `.learnings/INDEX.md`

### Required Metadata
Every new entry must include:

```markdown
**Skill**: conversation
```

### Hook Arbitration (when 2+ skills are enabled)
- Use one dispatcher hook as the single entrypoint.
- Dispatcher responsibilities: route by matcher, dedupe repeated events, and rate-limit reminders.
- Suggested defaults: dedupe key = `event + matcher + file + 5m_window`; max 1 reminder per skill every 5 minutes.

### Narrow Matcher Scope (conversation)
Only trigger this skill automatically for conversation signals such as:
- `tone mismatch|intent miss|hallucination|rephrase|clarification loop`
- `escalation needed|user frustration|context loss`
- explicit conversation intent in user prompt

### Cross-Skill Precedence
When guidance conflicts, apply:
1. `security`
2. `engineering`
3. `coding`
4. `ai`
5. user-explicit domain skill
6. `meta` as tie-breaker

### Ownership Rules
- This skill writes only to `.learnings/conversation/` in stackable mode.
- It may read other skill folders for cross-linking, but should not rewrite their entries.
- Standalone mode writes to this project's `.learnings/*.md` log files only.
- Stackable mode writes only to the namespaced folder above and must not rewrite other skills' log entries.
- Promotion into `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `MEMORY.md`, rules, hooks, or generated skills is not a logging write. Show a reviewed diff and apply only after explicit user approval.