Imported from aaddrick/written-voice-replication (.claude/skills/speech-act-pragmatic/SKILL.md). Install upstream with npx skills add aaddrick/written-voice-replication --skill speech-act-pragmatic. Copyright stays with the author.

Speech Act and Pragmatic Analysis

Overview

Speech act analysis classifies texts by their communicative function -- what the author is DOING with language (asserting, advising, explaining, questioning, challenging, agreeing/supporting) rather than what they are saying. By measuring the proportion of each speech act type across a corpus, the analysis produces a pragmatic signature: a distributional profile of how an author uses language to act in the world. The core principle: speech acts reveal communicative habits that persist across topics -- a person who predominantly explains and qualifies does so whether discussing technology, politics, or cooking. These proportions produce replicable constraints for voice matching that complement lexical, sentiment, and structural analyses.

Research foundation: Speech act theory originates with Austin (1962, How to Do Things with Words) who distinguished locutionary (saying), illocutionary (doing by saying), and perlocutionary (effect of saying) acts. Searle (1976) systematized this into five illocutionary categories: assertives (committing to truth), directives (getting hearer to do something), commissives (committing speaker to action), expressives (expressing psychological states), and declarations (bringing about states of affairs). The CMC Act Taxonomy (Herring, Das, & Penumarthy, 2005) adapted speech act theory to computer-mediated communication with 18 act types suitable for online discourse. For pragmatic analysis of written corpora, a hybrid approach combining dictionary-based signal detection with contextual classification produces the most reliable results (Zhang et al., 2011; Qadir & Riloff, 2011).

When to Use

• Categorizing posts, comments, or documents by what the author is doing (asserting, explaining, questioning, etc.)
• Measuring proportions of speech act types across a corpus to build a communicative profile
• Comparing how an author's communicative function shifts across topics, time periods, or contexts
• Building pragmatic constraints for voice replication ("this author advises 25% of the time, questions 15%")
• Identifying whether an author predominantly informs, persuades, supports, or challenges
• Complementing lexical and sentiment analyses with a functional layer

When NOT to use:

• Corpus contains fewer than 300 words total (see Insufficient Data Handling)
• All texts are single words or very short phrases (no illocutionary structure to classify)
• Goal is to determine speaker intent or sincerity (speech acts classify function, not intent)
• Text is machine-generated or heavily templated (speech act distributions reflect the template)
• You need to assess argument quality or persuasive effectiveness (this measures function, not effect)
• Translated text where pragmatic markers may reflect the translator's habits

digraph speech_act_decision {
    rankdir=TB;
    "Enough text?\n(300+ words, multi-sentence)" [shape=diamond];
    "Multiple texts or\nsubstantial length?" [shape=diamond];
    "Determining speaker\nintent or sincerity?" [shape=diamond];
    "Proceed with\nfull analysis" [shape=box];
    "Report insufficient\ndata" [shape=box];
    "Proceed with\nlimited scope caveat" [shape=box];
    "STOP: Wrong tool.\nThis classifies function,\nnot intent" [shape=box];

    "Enough text?\n(300+ words, multi-sentence)" -> "Multiple texts or\nsubstantial length?" [label="yes"];
    "Enough text?\n(300+ words, multi-sentence)" -> "Report insufficient\ndata" [label="no"];
    "Multiple texts or\nsubstantial length?" -> "Determining speaker\nintent or sincerity?" [label="yes"];
    "Multiple texts or\nsubstantial length?" -> "Proceed with\nlimited scope caveat" [label="no, single text"];
    "Determining speaker\nintent or sincerity?" -> "STOP: Wrong tool.\nThis classifies function,\nnot intent" [label="yes"];
    "Determining speaker\nintent or sincerity?" -> "Proceed with\nfull analysis" [label="no"];
}

Quick Reference

Speech Act Taxonomy for Written Discourse

This taxonomy is optimized for written online and offline text. It draws from Searle's (1976) illocutionary categories and the CMC Act Taxonomy (Herring et al., 2005), consolidated into six primary categories plus two secondary categories for practical classification.

Primary Speech Act Categories

Secondary Speech Act Categories

Classification Priority Rules

A single text often performs multiple speech acts. Apply these rules:

1. Identify the dominant act -- the primary communicative function of the text as a whole
2. Identify secondary acts -- subordinate functions that support or frame the dominant act
3. When ambiguous, prefer the act that best describes the OVERALL purpose, not individual sentences
4. Indirect speech acts are common -- a question ("Isn't it true that X?") may function as a challenge; an assertion ("You might want to try X") may function as advice. Classify by FUNCTION, not surface form.

Signal Phrase Dictionaries

import re
from collections import Counter

# Signal phrases for each speech act category.
# These are INDICATORS for initial classification, not deterministic rules.
# Context determines the actual speech act -- a question mark does not
# always indicate questioning (rhetorical questions may challenge).

SPEECH_ACT_SIGNALS = {
    'asserting': {
        'strong': [
            r'\b(?:I think|I believe|in my (?:opinion|view|experience))\b',
            r'\b(?:the (?:fact|truth|reality|point|thing) is)\b',
            r'\b(?:it is|it\'s|this is|that is|that\'s) (?:clear|obvious|true|false|wrong|right|correct|important)\b',
            r'\b(?:clearly|obviously|certainly|undeniably|undoubtedly)\b',
            r'\b(?:I (?:know|see|find|notice|realize|understand) that)\b',
        ],
        'moderate': [
            r'\b(?:actually|basically|essentially|fundamentally)\b',
            r'\b(?:the (?:problem|issue|challenge|question) (?:is|here is))\b',
            r'\b(?:it (?:seems|appears|turns out) (?:that)?)\b',
            r'\b(?:from what I (?:can see|understand|gather))\b',
        ],
    },
    'explaining': {
        'strong': [
            r'\b(?:because|the reason (?:is|being|for this))\b',
            r'\b(?:this (?:means|implies|suggests|indicates) (?:that)?)\b',
            r'\b(?:in other words|put (?:simply|differently)|what (?:this|I) mean[s]? is)\b',
            r'\b(?:to (?:explain|clarify|elaborate|illustrate))\b',
            r'\b(?:what happens is|the way (?:it|this) works)\b',
        ],
        'moderate': [
            r'\b(?:so (?:basically|essentially|what happens))\b',
            r'\b(?:for (?:example|instance)|such as|e\.g\.|i\.e\.)\b',
            r'\b(?:that is to say|namely|specifically)\b',
            r'\b(?:here\'s (?:why|how|what))\b',
        ],
    },
    'advising': {
        'strong': [
            r'\b(?:you should|you need to|you have to|you must)\b',
            r'\b(?:I (?:would |\'d )?recommend|I (?:would |\'d )?suggest)\b',
            r'\b(?:make sure (?:to|you)|be sure to|don\'t forget to)\b',
            r'\b(?:try (?:to |doing |using )?|consider (?:doing |using )?)\b',
            r'^(?:do|use|check|look at|start with|go with)\b',
        ],
        'moderate': [
            r'\b(?:you (?:might|could|may) (?:want to|try|consider))\b',
            r'\b(?:it (?:would be|might be|could be) (?:worth|good|better|helpful) (?:to)?)\b',
            r'\b(?:if I were you|in your (?:place|shoes|position))\b',
            r'\b(?:my (?:advice|suggestion|recommendation) (?:is|would be))\b',
            r'\b(?:pro tip|tip:|fwiw|for what it\'s worth)\b',
        ],
    },
    'questioning': {
        'strong': [
            r'\?$',  # Ends with question mark
            r'\b(?:does anyone (?:know|have|else))\b',
            r'\b(?:how (?:do|does|can|would|should|did) (?:you|I|we|one))\b',
            r'\b(?:what (?:is|are|was|were|do|does|would|should))\b',
            r'\b(?:can (?:someone|anyone|you) (?:explain|help|tell|point))\b',
            r'\b(?:is (?:there|it|this) (?:a|any|the))\b.*\?',
        ],
        'moderate': [
            r'\b(?:(?:I\'m |I am )?(?:wondering|curious) (?:if|about|whether))\b',
            r'\b(?:any (?:thoughts|ideas|suggestions|recommendations))\b',
            r'\b(?:has anyone (?:tried|used|experienced|seen))\b',
            r'\b(?:thoughts\??|opinions\??|suggestions\??)\b',
        ],
    },
    'challenging': {
        'strong': [
            r'\b(?:I disagree|I (?:don\'t|do not) (?:agree|think|believe))\b',
            r'\b(?:that\'s (?:not|wrong|incorrect|false|misleading|inaccurate))\b',
            r'\b(?:no,? (?:that\'s|it\'s|this is) (?:not|wrong))\b',
            r'\b(?:you\'re (?:wrong|mistaken|missing|ignoring|overlooking))\b',
            r'\b(?:this (?:is|seems) (?:wrong|incorrect|misleading|false))\b',
        ],
        'moderate': [
            r'\b(?:but (?:that|this|the|what about))\b',
            r'\b(?:(?:however|on the other hand|conversely),? )\b',
            r'\b(?:the (?:problem|issue|flaw) with (?:this|that|your))\b',
            r'\b(?:that (?:doesn\'t|does not) (?:make sense|hold up|follow|work))\b',
            r'\b(?:I\'m not (?:sure|convinced|persuaded) (?:that|about))\b',
        ],
    },
    'agreeing_supporting': {
        'strong': [
            r'\b(?:I (?:completely |totally |fully |strongly )?agree)\b',
            r'\b(?:exactly|precisely|absolutely|100%|this \^+)\b',
            r'\b(?:(?:great|good|excellent|fantastic) (?:point|answer|explanation|post))\b',
            r'^(?:this\.?|this!|same\.?|\+1|seconded|agreed)$',
            r'\b(?:you\'re (?:right|correct|absolutely right|spot on))\b',
        ],
        'moderate': [
            r'\b(?:I (?:also |additionally )?(?:think|feel|find) (?:the same|so too|similarly))\b',
            r'\b(?:fair (?:point|enough)|well (?:said|put))\b',
            r'\b(?:to add to (?:this|that|what|your point))\b',
            r'\b(?:building on (?:this|that|what))\b',
            r'\b(?:I (?:second|endorse|support|echo) (?:this|that|your))\b',
        ],
    },
}

# Secondary categories (used when primary categories don't fit well)
SECONDARY_SIGNALS = {
    'expressing': {
        'strong': [
            r'\b(?:I (?:love|hate|enjoy|despise|adore|loathe))\b',
            r'\b(?:(?:so |really |incredibly |extremely )?(?:frustrated|excited|amazed|disappointed|impressed|annoyed))\b',
            r'\b(?:ugh|wow|yikes|lol|omg|smh|sigh)\b',
            r'(?:!{2,})',  # Multiple exclamation marks
        ],
    },
    'commissive': {
        'strong': [
            r'\b(?:I (?:will|\'ll|am going to|plan to|intend to))\b',
            r'\b(?:let me (?:try|check|look|see|get back))\b',
            r'\b(?:I (?:promise|commit|pledge|guarantee))\b',
        ],
    },
}

Confidence Levels

Workflow

Copy this checklist and track progress:

Speech Act & Pragmatic Analysis Progress:
- [ ] Step 1: Validate corpus suitability and classify text units
- [ ] Step 2: Classify each text unit by primary and secondary speech acts
- [ ] Step 3: Compute speech act proportions and dominance profile
- [ ] Step 4: Analyze speech act distribution across contexts
- [ ] Step 5: Identify indirect speech acts and pragmatic patterns
- [ ] Step 6: Compute pragmatic signature and replication constraints
- [ ] Step 7: Write findings to docs/analysis/22-speech-act-pragmatic.md

Step 1: Validate Corpus Suitability

Before analysis, verify the corpus has sufficient material for speech act classification.

Suitability checks:

If corpus fails suitability: Report the failure. State what was checked, what failed, and why speech act analysis is unreliable. Do not force analysis on unsuitable data.

Defining text units: A text unit is the smallest independently classifiable segment. Typically:

• One post or comment = one text unit (for online corpora)
• One paragraph = one text unit (for long-form documents)
• One conversational turn = one text unit (for dialogue)

For long texts with multiple speech acts, segment at paragraph boundaries and classify each paragraph.

Step 2: Classify Each Text Unit

For each text unit, determine the primary and (optionally) secondary speech act.

Classification approach (hybrid: signal-based + contextual):

1. Signal scan: Match text against signal phrase dictionaries to identify candidate speech acts
2. Contextual override: Review candidates in context -- indirect speech acts are common; surface form may not match function
3. Dominance determination: Assign the primary speech act based on overall communicative purpose
4. Secondary assignment: If a subordinate function is clearly present, assign a secondary speech act

def classify_speech_act(text, context=None):
    """Classify a text unit by its primary speech act.

    Returns: {
        'primary': (act_label, confidence),
        'secondary': (act_label, confidence) or None,
        'signals_found': {act: [signals]},
        'is_indirect': bool,
        'notes': str
    }
    """
    text_lower = text.lower().strip()
    if len(text_lower.split()) < 3:
        return {
            'primary': ('indeterminate', 'n/a'),
            'secondary': None,
            'signals_found': {},
            'is_indirect': False,
            'notes': 'Text too short for reliable classification'
        }

    # Phase 1: Signal scan
    act_scores = {}
    signals_found = {}

    for act, signal_groups in SPEECH_ACT_SIGNALS.items():
        strong_count = 0
        moderate_count = 0
        found = []
        for pattern in signal_groups.get('strong', []):
            matches = re.findall(pattern, text_lower, re.IGNORECASE | re.MULTILINE)
            if matches:
                strong_count += len(matches)
                found.append(('strong', pattern, len(matches)))
        for pattern in signal_groups.get('moderate', []):
            matches = re.findall(pattern, text_lower, re.IGNORECASE | re.MULTILINE)
            if matches:
                moderate_count += len(matches)
                found.append(('moderate', pattern, len(matches)))

        # Weighted score: strong signals count double
        score = strong_count * 2 + moderate_count
        if score > 0:
            act_scores[act] = score
            signals_found[act] = found

    if not act_scores:
        return {
            'primary': ('indeterminate', 'low'),
            'secondary': None,
            'signals_found': {},
            'is_indirect': False,
            'notes': 'No clear speech act signals detected'
        }

    # Phase 2: Rank candidates
    ranked = sorted(act_scores.items(), key=lambda x: x[1], reverse=True)
    primary_act = ranked[0][0]
    primary_score = ranked[0][1]

    # Confidence determination
    if primary_score >= 4:
        confidence = 'high'
    elif primary_score >= 2:
        confidence = 'moderate'
    else:
        confidence = 'low'

    # Check for close second (potential multi-act or indirect)
    secondary = None
    is_indirect = False
    notes = ''

    if len(ranked) > 1:
        second_act = ranked[1][0]
        second_score = ranked[1][1]
        if second_score >= primary_score * 0.6:
            secondary = (second_act, 'moderate')
            notes = f'Close secondary: {second_act} (score ratio: {second_score/primary_score:.2f})'

        # Detect common indirect patterns
        if primary_act == 'questioning' and second_act == 'challenging':
            is_indirect = True
            notes += ' | Possible rhetorical question functioning as challenge'
        elif primary_act == 'asserting' and second_act == 'advising':
            is_indirect = True
            notes += ' | Possible indirect advice via assertion'

    return {
        'primary': (primary_act, confidence),
        'secondary': secondary,
        'signals_found': signals_found,
        'is_indirect': is_indirect,
        'notes': notes,
    }

Critical caveat -- indirect speech acts: Surface form frequently diverges from communicative function in written text:

When signal-based classification suggests one act but contextual reading suggests another, classify by function, not form. Note the indirectness in the classification record.

Step 3: Compute Speech Act Proportions

def compute_speech_act_profile(classifications):
    """Compute speech act proportions from a list of classifications.

    Args:
        classifications: list of dicts from classify_speech_act()

    Returns: dict with proportions, dominance ranking, and confidence metrics.
    """
    primary_counts = Counter()
    secondary_counts = Counter()
    confidence_counts = {'high': 0, 'moderate': 0, 'low': 0, 'n/a': 0}
    indirect_count = 0
    total = len(classifications)

    for c in classifications:
        primary_act, conf = c['primary']
        primary_counts[primary_act] += 1
        confidence_counts[conf] += 1

        if c['secondary']:
            sec_act, _ = c['secondary']
            secondary_counts[sec_act] += 1

        if c['is_indirect']:
            indirect_count += 1

    # Remove indeterminate from proportion calculations
    classifiable = total - primary_counts.get('indeterminate', 0)

    if classifiable == 0:
        return {
            'error': 'No classifiable texts',
            'total_texts': total,
            'indeterminate_count': primary_counts.get('indeterminate', 0),
        }

    # Compute proportions (excluding indeterminate)
    proportions = {}
    for act in ['asserting', 'explaining', 'advising', 'questioning',
                 'challenging', 'agreeing_supporting']:
        count = primary_counts.get(act, 0)
        proportions[act] = {
            'count': count,
            'proportion': round(count / classifiable, 3),
            'percentage': round(count / classifiable * 100, 1),
        }

    # Dominance ranking
    ranked = sorted(proportions.items(),
                    key=lambda x: x[1]['count'], reverse=True)

    # Pragmatic diversity: how evenly distributed are the speech acts?
    # Shannon entropy normalized to [0, 1]
    import math
    entropy = 0
    for act_data in proportions.values():
        p = act_data['proportion']
        if p > 0:
            entropy -= p * math.log2(p)
    max_entropy = math.log2(len(proportions))  # maximum if perfectly even
    normalized_entropy = entropy / max_entropy if max_entropy > 0 else 0

    return {
        'total_texts': total,
        'classifiable_texts': classifiable,
        'indeterminate_count': primary_counts.get('indeterminate', 0),
        'proportions': proportions,
        'dominance_ranking': [(act, data) for act, data in ranked],
        'dominant_act': ranked[0][0] if ranked else None,
        'dominant_proportion': ranked[0][1]['proportion'] if ranked else 0,
        'secondary_act_counts': dict(secondary_counts),
        'indirect_speech_act_count': indirect_count,
        'indirect_rate': round(indirect_count / max(total, 1), 3),
        'pragmatic_diversity': round(normalized_entropy, 3),
        'confidence_distribution': confidence_counts,
        'classification_rate': round(classifiable / max(total, 1), 3),
    }

Interpreting pragmatic diversity (normalized Shannon entropy):

Step 4: Analyze Distribution Across Contexts

If the corpus includes metadata (topic, subreddit, time period, audience), compare speech act distributions across contexts.

def compare_distributions(profile_a, profile_b, label_a='Context A', label_b='Context B'):
    """Compare speech act distributions between two contexts.
    Returns per-act differences and an overall shift metric."""
    acts = ['asserting', 'explaining', 'advising', 'questioning',
            'challenging', 'agreeing_supporting']

    comparisons = []
    total_shift = 0

    for act in acts:
        prop_a = profile_a['proportions'].get(act, {}).get('proportion', 0)
        prop_b = profile_b['proportions'].get(act, {}).get('proportion', 0)
        diff = prop_b - prop_a
        total_shift += abs(diff)

        comparisons.append({
            'act': act,
            f'{label_a}_pct': round(prop_a * 100, 1),
            f'{label_b}_pct': round(prop_b * 100, 1),
            'shift_pct': round(diff * 100, 1),
            'direction': 'increase' if diff > 0 else 'decrease' if diff < 0 else 'stable',
        })

    return {
        'comparisons': comparisons,
        'total_shift': round(total_shift, 3),
        'interpretation': (
            'minimal shift' if total_shift < 0.1 else
            'moderate shift' if total_shift < 0.3 else
            'substantial shift'
        ),
    }

What contextual shifts reveal:

• Shift from explaining to advising across topics may indicate domain confidence
• Shift from questioning to asserting over time may indicate growing expertise
• Shift from agreeing to challenging across audiences may indicate audience adaptation
• Stable distributions across contexts suggest deeply embedded communicative habits

Step 5: Identify Indirect Speech Acts and Pragmatic Patterns

Beyond individual classifications, look for corpus-level pragmatic patterns.

Patterns to detect:

Step 6: Compute Pragmatic Signature and Replication Constraints

Synthesize all findings into a pragmatic signature -- a compact profile of the author's communicative habits.

Pragmatic signature format:

## Pragmatic Signature

### Speech Act Distribution
| Act | Proportion | Rank | Replication Weight |
|-----|-----------|------|--------------------|
| [dominant act] | [X%] | 1 | HIGH |
| [second act] | [X%] | 2 | HIGH |
| [third act] | [X%] | 3 | MEDIUM |
| ... | ... | ... | LOW |

### Pragmatic Ratios
- Challenge-to-Agree ratio: [X.XX] ([confrontational/balanced/affiliative])
- Question-to-Explain ratio: [X.XX] ([inquiry-oriented/balanced/exposition-oriented])
- Indirect speech act rate: [X%] ([low/moderate/high])
- Pragmatic diversity: [X.XX] ([concentrated/moderate/diverse])

### Replication Constraints
1. [Top act] should appear in approximately [X]% of generated texts
2. [Second act] should appear in approximately [X]% of generated texts
3. Indirect speech acts should occur at [X]% rate
4. [Specific ratio constraint, e.g., "Challenge roughly twice as often as agree"]
5. [Context-specific constraint if applicable]

Replication weight assignment:

Step 7: Write the Report

Write all findings to docs/analysis/22-speech-act-pragmatic.md. See the report template below.

Report Output Template

The final report MUST be written to docs/analysis/22-speech-act-pragmatic.md with this structure:

# Speech Act and Pragmatic Analysis

## Methodology
- **Approach:** Hybrid signal-based + contextual speech act classification
- **Taxonomy:** Six primary acts (asserting, explaining, advising, questioning, challenging, agreeing/supporting) + two secondary acts (expressing, commissive), adapted from Searle (1976) and CMC Act Taxonomy (Herring et al., 2005)
- **Corpus:** [N words, N text units, date range, source description]
- **Classification method:** Signal phrase dictionary matching with contextual override for indirect speech acts
- **Confidence levels:** High (2+ strong signals), Moderate (1 strong or 2+ moderate), Low (ambiguous signals), Indeterminate (excluded from proportions)

## Corpus Suitability Assessment
- **Word count:** [N] words ([sufficient / insufficient / marginal])
- **Text unit count:** [N] units ([sufficient for proportions / raw counts only])
- **Multi-sentence texts:** [N] of [N] texts have 2+ sentences ([X%])
- **Language:** [English / mixed]
- **Authorship:** [single / multiple / unknown]
- **Contextual diversity:** [list contexts/topics present]
- **Platform conventions:** [platform norms that may bias speech act distribution]
- **Overall suitability:** [suitable / suitable with caveats / unsuitable]

## Speech Act Distribution

### Primary Speech Acts

| Speech Act | Count | Proportion | Percentage | Confidence (High/Mod/Low) |
|-----------|-------|-----------|------------|--------------------------|
| Asserting | [N] | [X.XXX] | [X.X%] | [N] / [N] / [N] |
| Explaining | [N] | [X.XXX] | [X.X%] | [N] / [N] / [N] |
| Advising | [N] | [X.XXX] | [X.X%] | [N] / [N] / [N] |
| Questioning | [N] | [X.XXX] | [X.X%] | [N] / [N] / [N] |
| Challenging | [N] | [X.XXX] | [X.X%] | [N] / [N] / [N] |
| Agreeing/Supporting | [N] | [X.XXX] | [X.X%] | [N] / [N] / [N] |
| **Classifiable total** | **[N]** | **1.000** | **100%** | |
| Indeterminate | [N] | -- | -- | |

**Dominant speech act:** [act] ([X%])
**Classification rate:** [X%] of text units successfully classified

### Secondary Speech Acts (where detected)
| Speech Act | Count | Notes |
|-----------|-------|-------|
| Expressing | [N] | [context notes] |
| Commissive | [N] | [context notes] |

### Dominance Ranking
1. [Act]: [X%] -- [interpretation of what this dominance means for communicative style]
2. [Act]: [X%]
3. [Act]: [X%]
4. [Act]: [X%]
5. [Act]: [X%]
6. [Act]: [X%]

## Pragmatic Ratios and Metrics

| Metric | Value | Interpretation |
|--------|-------|----------------|
| Challenge-to-Agree ratio | [X.XX] | [confrontational / balanced / affiliative] |
| Question-to-Explain ratio | [X.XX] | [inquiry-oriented / balanced / exposition-oriented] |
| Indirect speech act rate | [X%] | [low (<10%) / moderate (10-20%) / high (>20%)] |
| Pragmatic diversity (entropy) | [X.XX] | [concentrated / moderate / diverse] |
| Advising density | [X%] | [low / moderate / high -- authoritative/helpful posture indicator] |

## Indirect Speech Act Analysis

| Indirect Pattern | Count | Example | Surface Form -> Actual Function |
|-----------------|-------|---------|-------------------------------|
| [pattern] | [N] | [example from corpus] | [form] -> [function] |

**Overall indirect rate:** [X%] of classified texts contain indirect speech acts
**Most common indirect pattern:** [description]

## Contextual Distribution Comparison
[If multiple contexts available]

| Speech Act | [Context A] | [Context B] | Shift | Direction |
|-----------|-------------|-------------|-------|-----------|
| Asserting | [X%] | [X%] | [+/-X%] | [increase/decrease/stable] |
| Explaining | [X%] | [X%] | [+/-X%] | [increase/decrease/stable] |
| ... | ... | ... | ... | ... |

**Total shift magnitude:** [X.XXX] ([minimal / moderate / substantial])
**Key contextual findings:** [What do the shifts reveal about audience adaptation, topic expertise, or communicative flexibility?]

## Pragmatic Signature

### Speech Act Profile
| Act | Proportion | Rank | Replication Weight |
|-----|-----------|------|--------------------|
| [act] | [X%] | 1 | HIGH |
| [act] | [X%] | 2 | HIGH |
| [act] | [X%] | 3 | MEDIUM |
| [act] | [X%] | 4 | LOW |
| [act] | [X%] | 5 | LOW |
| [act] | [X%] | 6 | LOW |

### Pragmatic Constraints for Voice Replication
| Constraint | Value | Priority |
|-----------|-------|----------|
| Dominant act proportion | [act] at ~[X%] | HIGH |
| Secondary act proportion | [act] at ~[X%] | HIGH |
| Challenge-to-agree ratio | ~[X.XX] | [HIGH if extreme, else MEDIUM] |
| Indirect speech act rate | ~[X%] | [HIGH if >15%, else LOW] |
| Pragmatic diversity target | [X.XX] ([concentrated/diverse]) | MEDIUM |
| [Context-specific constraint] | [value] | [priority] |

### Composite Pragmatic Style
[1-2 sentence characterization: e.g., "Predominantly explanatory-assertive style with moderate advising. Low challenge rate and high indirect speech act usage suggest a cooperative, non-confrontational communicative posture that teaches rather than argues."]

## Limitations and Caveats
- Signal-based classification uses surface-level linguistic markers. Indirect speech acts (estimated at [X%] of this corpus) are identified through contextual heuristics, not deep pragmatic parsing.
- Speech act classification is inherently judgment-based. Inter-annotator agreement in published studies typically ranges from kappa = 0.65-0.80 for coarse categories. Automated signal-matching may fall below this.
- Proportions are meaningful only with sufficient text units (10+ recommended). With [N] text units, the margin of error on proportions is approximately +/- [computed or estimated margin].
- Speech act distributions are context-sensitive. This profile reflects the author's communicative habits IN THIS CORPUS and may differ in other contexts, audiences, or platforms.
- The taxonomy collapses Searle's five categories into six primary acts optimized for written discourse. Declarations (performatives) are excluded as they are rare in non-institutional written text.
- Platform conventions may bias distributions: Q&A sites inflate questioning/explaining; debate forums inflate challenging; social platforms inflate agreeing/expressing.
- [Corpus-specific limitations from Step 1]
- These results describe communicative FUNCTION, not speaker INTENT. An author who frequently challenges may do so out of intellectual rigor, hostility, or pedagogical habit -- speech act analysis cannot distinguish these motivations.

## References
- Austin, J.L. (1962). *How to Do Things with Words*. Oxford University Press.
- Searle, J.R. (1976). A classification of illocutionary acts. *Language in Society*, 5(1), 1-23.
- Herring, S.C., Das, A., & Penumarthy, S. (2005). CMC Act Taxonomy. Indiana University.
- Zhang, R., Gao, D., & Li, W. (2011). What are tweeters doing: Recognizing speech acts in Twitter. *AAAI-11 Workshop on Analyzing Microtext*.
- Qadir, A. & Riloff, E. (2011). Classifying sentences as speech acts in message board posts. *EMNLP 2011*.
- Bach, K. & Harnish, R.M. (1979). *Linguistic Communication and Speech Acts*. MIT Press.
- Jurafsky, D. et al. (1997). Automatic detection of discourse structure for speech recognition and understanding. *IEEE Workshop on Automatic Speech Recognition and Understanding*.

Good Patterns

• Classify by communicative function, not surface form -- "Have you tried X?" is advice disguised as a question; classify it as advising
• Use a clear, consolidated taxonomy -- six primary acts are enough for written discourse; finer-grained taxonomies reduce reliability without adding insight
• Combine signal-based detection with contextual classification -- dictionaries find candidates, human/LLM judgment resolves ambiguity
• Report proportions, not just counts -- "35% asserting, 25% explaining" is interpretable; "47 assertions, 33 explanations" is not
• Assign confidence levels per classification -- distinguish high-confidence from ambiguous classifications; report confidence distributions
• Compute pragmatic diversity -- a single dominance number misses whether the remaining acts are evenly spread or all concentrated in one alternative
• Compare distributions across contexts -- a stable distribution reveals deep communicative habits; shifts reveal audience adaptation
• Produce replicable pragmatic constraints -- the output should specify target proportions, not just describe patterns
• Flag indirect speech acts explicitly -- indirect acts are common (10-25% in most corpora) and are the single largest source of misclassification
• Use the pragmatic signature as a voice differentiator -- two authors with identical vocabulary may have very different speech act profiles

Anti-Patterns

Boundaries

This skill SHOULD produce:

• Classification of each text unit by primary (and optionally secondary) speech act with confidence levels
• Speech act proportion distribution across the corpus with dominance ranking
• Pragmatic ratios (challenge-to-agree, question-to-explain, advising density) as voice differentiators
• Indirect speech act detection with rate measurement and pattern identification
• Contextual distribution comparisons when metadata supports it
• Pragmatic diversity measurement (Shannon entropy) for distributional characterization
• A pragmatic signature with ranked proportions and replicable constraints for voice matching
• Written report at docs/analysis/22-speech-act-pragmatic.md

This skill should NOT:

• Claim to capture speaker intent, sincerity, or psychological motivation from speech act distributions
• Ignore indirect/implied speech acts (which are common and cause systematic bias if missed)
• Use pragmatic analysis for deception detection, credibility assessment, or trustworthiness scoring
• Assume speech acts map 1:1 to linguistic forms (surface form frequently diverges from function)
• Generalize a context-bound pragmatic profile to all contexts the author writes in
• Treat speech act classifications as deterministic (they are probabilistic and judgment-dependent)
• Use this analysis to make evaluative claims about communication quality or effectiveness
• Attribute personality traits or character assessments from speech act proportions
• Compute proportions from fewer than 10 text units (report raw counts only)
• Apply the English signal dictionaries to non-English text without adaptation

Insufficient Data Handling

digraph insufficient_data {
    rankdir=TB;
    node [shape=diamond, style=filled, fillcolor="#f0f0f0"];

    start [label="Total word count?", shape=diamond];
    tiny [label="< 300 words", shape=box, fillcolor="#ffcccc"];
    small [label="300-1,000 words", shape=box, fillcolor="#fff3cc"];
    moderate [label="1,000-3,000 words", shape=box, fillcolor="#ffffcc"];
    good [label="3,000+ words", shape=box, fillcolor="#ccffcc"];

    start -> tiny [label="< 300"];
    start -> small [label="300-1,000"];
    start -> moderate [label="1,000-3,000"];
    start -> good [label="3,000+"];

    tiny_action [label="STOP: Report insufficient data.\nDo NOT classify speech acts\nor compute proportions.\nReport only word count.", shape=box, fillcolor="#ffcccc"];
    small_action [label="Classify texts but\nreport RAW COUNTS only.\nDo NOT compute proportions.\nFlag LOW CONFIDENCE.", shape=box, fillcolor="#fff3cc"];
    moderate_action [label="Full classification.\nCompute proportions with\nMODERATE confidence.\nContextual comparison limited.", shape=box, fillcolor="#ffffcc"];
    good_action [label="Full analysis pipeline.\nAll features available.\nReliable pragmatic signature.", shape=box, fillcolor="#ccffcc"];

    tiny -> tiny_action;
    small -> small_action;
    moderate -> moderate_action;
    good -> good_action;
}

Common Mistakes

References

• Austin, J.L. (1962). How to Do Things with Words. Oxford University Press.
• Searle, J.R. (1976). A classification of illocutionary acts. Language in Society, 5(1), 1-23.
• Herring, S.C., Das, A., & Penumarthy, S. (2005). CMC Act Taxonomy.
• Speech Acts (Stanford Encyclopedia of Philosophy).
• Zhang, R., Gao, D., & Li, W. (2011). What are tweeters doing: Recognizing speech acts in Twitter. AAAI-11 Workshop on Analyzing Microtext.
• Qadir, A. & Riloff, E. (2011). Classifying sentences as speech acts in message board posts. EMNLP 2011.
• Bach, K. & Harnish, R.M. (1979). Linguistic Communication and Speech Acts. MIT Press.
• Jurafsky, D. (2004). Pragmatics and Computational Linguistics. In Handbook of Pragmatics.
• Viera, A.J. & Garrett, J.M. (2005). Understanding interobserver agreement: the kappa statistic. Family Medicine, 37(5), 360-363.
• Herring, S.C. (2010). Introduction to the pragmatics of computer-mediated communication.