Self-Improving Conversation

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, and important patterns get promoted to project memory.

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:

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nTone mismatches, context losses, hallucinations, and dialogue insights captured during conversations.\n\nCategories: 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.

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 | Promote to SOUL.md (tone/style), AGENTS.md (dialogue workflow), or TOOLS.md (integration) |

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):

clawdhub install self-improving-conversation

Manual:

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

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

Then create the log files (or copy from assets/):

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

For automatic reminders at session start:

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:

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:

## [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:

## [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

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:

## [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

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:

### 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:

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

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. Add to appropriate section in target file (create file if needed) 3. 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: " .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

Quick Status Check

# 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

Detection Triggers

Automatically log when you notice:

Tone Mismatches (→ learning with tone_mismatch category):

Misunderstandings (→ dialogue issue):

Escalation Failures (→ dialogue issue with escalation_failure):

Context Loss (→ learning with context_loss category):

Sentiment Drift (→ learning with sentiment_drift category):

Hallucination (→ learning with hallucination category):

Feature Gaps (→ feature request):

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):

.learnings/

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

Track learnings in repo (team-wide): Don't add to .gitignore — learnings become shared knowledge.

Hybrid (track templates, ignore entries):

.learnings/*.md
!.learnings/.gitkeep

Hook Integration

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

Quick Setup (Claude Code / Codex)

Create .claude/settings.json in your project:

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-conversation/scripts/activator.sh"
      }]
    }]
  }
}

This injects a dialogue learning evaluation reminder after each prompt (~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

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):

   ./skills/self-improving-conversation/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improving-conversation/scripts/extract-skill.sh skill-name
   

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

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:

## 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:

Stackability Contract (Standalone + Multi-Skill)

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

Namespaced Logging (recommended for 2+ skills)

Required Metadata

Skill: conversation

Hook Arbitration (when 2+ skills are enabled)

Narrow Matcher Scope (conversation)

Cross-Skill Precedence

Ownership Rules

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