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

Rhetorical and Discourse Structure Analysis

Overview

Analyze how an author constructs arguments and organizes text beyond the word level: argument ordering (claim-first vs. evidence-first vs. dialectical), rhetorical devices (hedging, concessions, rhetorical questions, analogies), discourse marker usage by functional type, and paragraph/post structural habits (length distributions, list vs. prose ratios, summary positions). The core principle: discourse structure reveals argumentation habits that are more stable across topics than word choice -- a person who leads with evidence before stating conclusions does so whether discussing technology, politics, or cooking. These structural patterns produce replicable constraints for voice matching that complement but do not duplicate lexical or sentiment analysis.

Research foundation: Rhetorical Structure Theory (Mann & Thompson, 1988) established that texts have hierarchical discourse relations between nucleus (core content) and satellite (supporting content) units. The enhanced RST framework (eRST; Zeldes, 2024, Computational Linguistics 51(1)) extends this to discourse relation graphs with non-projective and concurrent relations plus explicit signaling. Argument mining research (Lawrence & Reed, 2019, Computational Linguistics 45(4)) formalized the pipeline of component identification, component classification (claim vs. premise), and structure identification (support/attack relations). Fraser's (1999) taxonomy of discourse markers classifies them by function: contrastive ("but", "however"), elaborative ("moreover", "also"), inferential ("therefore", "thus"), and topic-management ("anyway", "so"). Hedge detection research (Medlock & Briscoe, 2007; Vincze et al., 2008) established lexicon-based and syntactic approaches to identifying epistemic uncertainty markers.

When to Use

• Characterizing how an author orders arguments (do they lead with claims or evidence?)
• Quantifying rhetorical device frequency: hedges, concessions, rhetorical questions, analogies
• Profiling discourse marker usage patterns by functional type (contrastive, elaborative, inferential)
• Analyzing structural habits: paragraph length distributions, list-vs-prose ratios, summary positioning
• Building structural constraints for voice replication that go beyond word choice and sentiment
• Comparing argumentation styles across authors or across time periods for the same author

When NOT to use:

• Corpus contains fewer than 500 words total (see Insufficient Data Handling)
• All texts are single sentences (no paragraph or argument structure to analyze)
• Goal is to assess argument quality or persuasive effectiveness (this measures structure, not effect)
• Text is heavily formatted by a platform (e.g., auto-generated templates) where structure reflects the tool, not the author
• Translated text where discourse markers and argument ordering may reflect the translator's habits

digraph discourse_decision {
    rankdir=TB;
    "Enough text?\n(500+ words, multi-sentence)" [shape=diamond];
    "Multiple texts or\nparagraphs?" [shape=diamond];
    "Assessing argument\nquality/effectiveness?" [shape=diamond];
    "Proceed with\nfull analysis" [shape=box];
    "Report insufficient\nstructure" [shape=box];
    "Proceed with\nlimited scope caveat" [shape=box];
    "STOP: Wrong tool.\nThis measures structure,\nnot effectiveness" [shape=box];

    "Enough text?\n(500+ words, multi-sentence)" -> "Multiple texts or\nparagraphs?" [label="yes"];
    "Enough text?\n(500+ words, multi-sentence)" -> "Report insufficient\nstructure" [label="no"];
    "Multiple texts or\nparagraphs?" -> "Assessing argument\nquality/effectiveness?" [label="yes"];
    "Multiple texts or\nparagraphs?" -> "Proceed with\nlimited scope caveat" [label="no, single text"];
    "Assessing argument\nquality/effectiveness?" -> "STOP: Wrong tool.\nThis measures structure,\nnot effectiveness" [label="yes"];
    "Assessing argument\nquality/effectiveness?" -> "Proceed with\nfull analysis" [label="no"];
}

Quick Reference

Argument Ordering Patterns

Discourse Marker Categories (Fraser 1999 taxonomy, extended)

Rhetorical Devices

Structural Metrics

Workflow

Copy this checklist and track progress:

Rhetorical & Discourse Structure Analysis Progress:
- [ ] Step 1: Validate corpus suitability and structural richness
- [ ] Step 2: Classify argument ordering patterns per text
- [ ] Step 3: Detect and count discourse markers by functional type
- [ ] Step 4: Measure rhetorical device frequencies
- [ ] Step 5: Analyze paragraph and post structure distributions
- [ ] Step 6: Compute structural profile and cross-dimension patterns
- [ ] Step 7: Write findings to docs/analysis/20-rhetorical-discourse-structure.md

Step 1: Validate Corpus Suitability

Before analysis, verify the corpus has sufficient structural material to analyze.

Suitability checks:

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

Step 2: Classify Argument Ordering Patterns

For each text of sufficient length (3+ sentences), classify its primary argument ordering pattern.

Classification approach:

1. Identify the main claim -- what position or conclusion does the text advance?
2. Identify supporting elements -- evidence, examples, reasoning, concessions
3. Map the sequence -- does the claim appear before, after, or interleaved with support?
4. Assign pattern -- match to the five ordering types (claim-first, evidence-first, dialectical, exploratory, narrative-embedded)

import re
from collections import Counter

# Signal phrases that suggest ordering patterns.
# These are INDICATORS, not deterministic classifiers.
# A text with "I think" at the start may still be evidence-first
# if the body presents data before restating the claim.

CLAIM_FIRST_SIGNALS = [
    r'^I think\b', r'^I believe\b', r'^My view is\b',
    r'^In my opinion\b', r'^The answer is\b', r'^Here\'s the thing\b',
    r'^The point is\b', r'^My position is\b',
]

EVIDENCE_FIRST_SIGNALS = [
    r'\btherefore\b', r'\bthus\b', r'\bhence\b',
    r'\bso (?:it|we|I|this)\b', r'\bthis (?:shows|means|suggests|indicates)\b',
    r'\bgiven (?:that|this)\b', r'\blooking at\b',
    r'\bthe data (?:shows|suggests)\b',
]

DIALECTICAL_SIGNALS = [
    r'\bsome (?:say|argue|think|believe)\b',
    r'\bwhile (?:it\'s|this is|that is) true\b',
    r'\bon the other hand\b', r'\bopponents (?:say|argue)\b',
    r'\bthe counterargument\b', r'\bcritics (?:say|argue|point)\b',
]

CONCESSIVE_PAIRS = [
    (r'\badmittedly\b', r'\bbut\b'),
    (r'\bgranted\b', r'\bhowever\b'),
    (r'\bwhile I agree\b', r'\bI (?:think|believe|maintain)\b'),
    (r'\bto be fair\b', r'\bbut\b'),
]

def classify_argument_order(text):
    """Classify the primary argument ordering pattern of a text.
    Returns (pattern_label, confidence, signals_found).
    Confidence: 'high' if multiple signals converge, 'low' if ambiguous."""
    text_lower = text.lower()
    sentences = re.split(r'[.!?]+', text)
    sentences = [s.strip() for s in sentences if s.strip()]
    if len(sentences) < 3:
        return ('too_short', 'n/a', [])

    first_third = ' '.join(sentences[:max(len(sentences)//3, 1)])
    last_third = ' '.join(sentences[-max(len(sentences)//3, 1):])

    signals = {'claim_first': [], 'evidence_first': [],
               'dialectical': [], 'exploratory': []}

    # Check claim-first: claim signals in first third
    for pattern in CLAIM_FIRST_SIGNALS:
        if re.search(pattern, first_third, re.IGNORECASE):
            signals['claim_first'].append(pattern)

    # Check evidence-first: inferential markers in last third
    for pattern in EVIDENCE_FIRST_SIGNALS:
        if re.search(pattern, last_third, re.IGNORECASE):
            signals['evidence_first'].append(pattern)

    # Check dialectical: concessive structure
    for pattern in DIALECTICAL_SIGNALS:
        if re.search(pattern, text_lower):
            signals['dialectical'].append(pattern)

    # Determine dominant pattern
    counts = {k: len(v) for k, v in signals.items()}
    if max(counts.values()) == 0:
        return ('indeterminate', 'low', [])

    dominant = max(counts, key=counts.get)
    confidence = 'high' if counts[dominant] >= 2 else 'low'
    return (dominant, confidence, signals[dominant])

Important caveats for argument ordering classification:

• Signal phrases are indicators, not proof. A text starting with "I think" may still present evidence before the actual claim.
• Many texts use hybrid patterns. Assign the DOMINANT pattern but note secondary patterns.
• Short texts (under 3 sentences) cannot be reliably classified. Mark as "too_short."
• The same discourse marker can serve different functions in different contexts (see Anti-Patterns).

Aggregate across corpus:

def compute_ordering_profile(texts):
    """Compute argument ordering distribution across a corpus."""
    classifications = [classify_argument_order(t) for t in texts]
    pattern_counts = Counter(c[0] for c in classifications)
    total_classified = sum(v for k, v in pattern_counts.items()
                          if k not in ('too_short', 'indeterminate'))
    high_confidence = sum(1 for c in classifications if c[1] == 'high')

    return {
        'pattern_distribution': dict(pattern_counts),
        'total_classified': total_classified,
        'high_confidence_count': high_confidence,
        'dominant_pattern': pattern_counts.most_common(1)[0]
            if total_classified > 0 else ('indeterminate', 0),
        'classification_rate': total_classified / max(len(texts), 1),
    }

Step 3: Detect and Count Discourse Markers by Functional Type

Count discourse markers using a dictionary-based approach, categorized by Fraser's functional taxonomy.

DISCOURSE_MARKERS = {
    'contrastive': [
        'but', 'however', 'although', 'though', 'nevertheless',
        'nonetheless', 'yet', 'still', 'whereas', 'despite',
        'in contrast', 'on the other hand', 'on the contrary',
        'conversely', 'instead', 'rather', 'while',
    ],
    'elaborative': [
        'also', 'moreover', 'furthermore', 'in addition',
        'additionally', 'specifically', 'for example', 'for instance',
        'in fact', 'indeed', 'in particular', 'that is',
        'namely', 'such as', 'especially', 'notably',
    ],
    'inferential': [
        'therefore', 'thus', 'hence', 'so', 'consequently',
        'as a result', 'accordingly', 'it follows',
        'this means', 'this suggests', 'this implies',
        'which means', 'because of this',
    ],
    'topic_management': [
        'anyway', 'now', 'well', 'regarding', 'as for',
        'speaking of', 'incidentally', 'by the way',
        'moving on', 'turning to', 'back to',
    ],
    'concessive': [
        'admittedly', 'granted', 'to be fair', 'fair enough',
        'i concede', 'i admit', 'true', 'of course',
        'naturally', 'sure', 'no doubt',
    ],
    'emphatic': [
        'clearly', 'obviously', 'certainly', 'definitely',
        'undeniably', 'absolutely', 'without doubt',
        'undoubtedly', 'plainly', 'evidently',
    ],
}

def count_discourse_markers(text):
    """Count discourse markers by functional category.
    Returns per-category counts and per-1000-word rates."""
    text_lower = text.lower()
    words = text_lower.split()
    total_words = len(words)
    if total_words == 0:
        return None

    counts = {}
    for category, markers in DISCOURSE_MARKERS.items():
        cat_count = 0
        found_markers = []
        for marker in markers:
            # Use word boundary matching for multi-word markers
            occurrences = len(re.findall(
                r'\b' + re.escape(marker) + r'\b', text_lower
            ))
            if occurrences > 0:
                cat_count += occurrences
                found_markers.append((marker, occurrences))
        counts[category] = {
            'count': cat_count,
            'rate_per_1000': cat_count / total_words * 1000,
            'markers_found': found_markers,
        }

    counts['total_markers'] = sum(c['count'] for c in counts.values()
                                  if isinstance(c, dict))
    counts['total_rate_per_1000'] = (
        counts['total_markers'] / total_words * 1000
    )
    return counts

Critical caveat -- polysemy of discourse markers: The word "so" can be inferential ("So we conclude..."), topic-management ("So, what happened next?"), or a filler. The word "well" can be topic-management ("Well, let me explain"), a hedge ("Well, maybe"), or literal ("a well of water"). Dictionary-based counting cannot disambiguate these. Document this limitation. For high-stakes analysis, manually review the top 5 most frequent markers in context.

Step 4: Measure Rhetorical Device Frequencies

HEDGE_MARKERS = {
    'modal_verbs': ['might', 'could', 'may', 'would'],
    'epistemic_adverbs': [
        'perhaps', 'probably', 'possibly', 'arguably',
        'seemingly', 'apparently', 'supposedly', 'allegedly',
    ],
    'cognitive_verbs': [
        'i think', 'i believe', 'i suppose', 'i guess',
        'i imagine', 'i feel', 'it seems', 'it appears',
    ],
    'approximators': [
        'about', 'around', 'roughly', 'approximately',
        'sort of', 'kind of', 'somewhat', 'fairly',
        'rather', 'tend to',
    ],
    'shields': [
        'in my opinion', 'from my perspective',
        'as far as i know', 'to my knowledge',
        'in my experience', 'i could be wrong',
    ],
}

RHETORICAL_QUESTION_PATTERNS = [
    r'(?:who|what|how|why|where|when)\s+(?:would|could|can|does|is|are|was|were)\s+.*\?',
    r'(?:isn\'t|aren\'t|doesn\'t|don\'t|won\'t|can\'t|couldn\'t|wouldn\'t)\s+.*\?',
    r'(?:right|really|seriously|honestly)\s*\?',
]

ANALOGY_SIGNALS = [
    r'\blike (?:trying|having|being|watching|living)\b',
    r'\bas if\b', r'\bsimilar to\b', r'\banalogous to\b',
    r'\bthink of it as\b', r'\bimagine (?:a|that|if)\b',
    r'\bthe equivalent of\b', r'\bjust as\b.*\bso too\b',
    r'\bit\'s (?:like|as though)\b',
]

def measure_rhetorical_devices(text):
    """Measure frequency of rhetorical devices in text.
    Returns counts and rates per 1000 words."""
    text_lower = text.lower()
    words = text_lower.split()
    total_words = len(words)
    sentences = re.split(r'[.!?]+', text)
    sentences = [s.strip() for s in sentences if s.strip()]
    total_sentences = max(len(sentences), 1)

    if total_words == 0:
        return None

    # Hedging
    hedge_counts = {}
    total_hedges = 0
    for category, markers in HEDGE_MARKERS.items():
        cat_count = sum(
            len(re.findall(r'\b' + re.escape(m) + r'\b', text_lower))
            for m in markers
        )
        hedge_counts[category] = cat_count
        total_hedges += cat_count

    # Rhetorical questions
    rq_count = sum(
        len(re.findall(p, text_lower))
        for p in RHETORICAL_QUESTION_PATTERNS
    )

    # Analogies
    analogy_count = sum(
        len(re.findall(p, text_lower))
        for p in ANALOGY_SIGNALS
    )

    # Concession-contrast pairs (concessive marker followed by contrastive)
    concession_count = 0
    for sent in sentences:
        sent_lower = sent.lower()
        has_concessive = any(
            re.search(r'\b' + re.escape(m) + r'\b', sent_lower)
            for m in DISCOURSE_MARKERS['concessive']
        )
        has_contrastive = any(
            re.search(r'\b' + re.escape(m) + r'\b', sent_lower)
            for m in DISCOURSE_MARKERS['contrastive']
        )
        if has_concessive and has_contrastive:
            concession_count += 1

    return {
        'hedging': {
            'total': total_hedges,
            'rate_per_1000': total_hedges / total_words * 1000,
            'by_type': hedge_counts,
        },
        'rhetorical_questions': {
            'count': rq_count,
            'rate_per_sentence': rq_count / total_sentences,
        },
        'analogies': {
            'count': analogy_count,
            'rate_per_1000': analogy_count / total_words * 1000,
        },
        'concession_contrast_pairs': {
            'count': concession_count,
            'rate_per_sentence': concession_count / total_sentences,
        },
    }

Important: hedging in genuinely uncertain contexts. Not all hedging is rhetorical strategy. In scientific writing or genuinely uncertain situations, hedges like "might", "could", and "it seems" reflect actual epistemic state, not a discourse habit. When the corpus is domain-specific technical writing, discount hedge frequency by noting the genre baseline. Do NOT over-count hedges in contexts where uncertainty is the appropriate epistemic stance.

Step 5: Analyze Paragraph and Post Structure

def analyze_structure(text):
    """Analyze paragraph-level structural patterns."""
    # Split into paragraphs (double newline or significant whitespace)
    paragraphs = re.split(r'\n\s*\n', text)
    paragraphs = [p.strip() for p in paragraphs if p.strip()]

    if not paragraphs:
        return None

    # Paragraph metrics
    para_word_counts = [len(p.split()) for p in paragraphs]
    para_sentence_counts = [
        len([s for s in re.split(r'[.!?]+', p) if s.strip()])
        for p in paragraphs
    ]

    # List detection: paragraphs containing bullet/number markers
    list_pattern = r'(?:^|\n)\s*(?:[-*+]|\d+[.)]|\([a-z]\))\s+'
    list_paragraphs = sum(
        1 for p in paragraphs if re.search(list_pattern, p)
    )

    # Summary position detection
    # Heuristic: the paragraph with the highest density of inferential
    # markers and claim-first signals is likely the summary
    summary_position = 'distributed'
    if len(paragraphs) >= 3:
        inferential_density = []
        for p in paragraphs:
            p_lower = p.lower()
            density = sum(
                len(re.findall(r'\b' + re.escape(m) + r'\b', p_lower))
                for m in DISCOURSE_MARKERS.get('inferential', [])
            )
            inferential_density.append(density)
        if inferential_density:
            max_idx = inferential_density.index(max(inferential_density))
            if max_idx == 0:
                summary_position = 'opening'
            elif max_idx == len(paragraphs) - 1:
                summary_position = 'closing'
            else:
                summary_position = 'middle'

    import statistics
    return {
        'paragraph_count': len(paragraphs),
        'avg_paragraph_length': statistics.mean(para_word_counts),
        'median_paragraph_length': statistics.median(para_word_counts),
        'paragraph_length_std': (
            statistics.stdev(para_word_counts)
            if len(para_word_counts) > 1 else 0
        ),
        'min_paragraph_length': min(para_word_counts),
        'max_paragraph_length': max(para_word_counts),
        'avg_sentences_per_paragraph': statistics.mean(para_sentence_counts),
        'list_paragraph_count': list_paragraphs,
        'list_to_prose_ratio': list_paragraphs / max(len(paragraphs), 1),
        'summary_position': summary_position,
        'paragraph_length_distribution': para_word_counts,
    }

Step 6: Compute Structural Profile and Cross-Dimension Patterns

Synthesize findings from Steps 2-5 into a unified structural profile describing the author's discourse habits.

Profile structure:

## Discourse Structure Profile

### Argument Ordering
| Pattern | Frequency | Percentage | Confidence |
|---------|-----------|------------|------------|
| [pattern] | [N] | [X%] | [high/low] |

Dominant pattern: [X] ([N]% of classified texts)

### Discourse Marker Profile
| Category | Rate per 1000 words | Most Used Markers |
|----------|---------------------|-------------------|
| Contrastive | [X.X] | [marker1, marker2] |
| Elaborative | [X.X] | [marker1, marker2] |
| Inferential | [X.X] | [marker1, marker2] |
| Concessive | [X.X] | [marker1, marker2] |
| Emphatic | [X.X] | [marker1, marker2] |
| Topic-management | [X.X] | [marker1, marker2] |
Total marker density: [X.X] per 1000 words

### Rhetorical Device Profile
| Device | Rate | Interpretation |
|--------|------|----------------|
| Hedging | [X.X] per 1000 words | [low/moderate/high -- see thresholds] |
| Rhetorical questions | [X.X] per 100 sentences | [rare/occasional/frequent] |
| Analogies | [X.X] per 1000 words | [rare/occasional/frequent] |
| Concession-contrast pairs | [X.X] per 100 sentences | [rare/occasional/frequent] |

### Structural Habits
| Metric | Value | Interpretation |
|--------|-------|----------------|
| Avg paragraph length | [N] words | [short/moderate/long] |
| Paragraph length variance | [N] std dev | [consistent/varied/highly varied] |
| List-to-prose ratio | [X.X] | [prose-dominant/mixed/list-heavy] |
| Summary position | [opening/closing/distributed] | [top-down/bottom-up/distributed] |
| Sentences per paragraph | [N] | [terse/moderate/dense] |

Interpretation thresholds (approximate baselines from published research):

Cross-dimension patterns to look for:

• Hedging + concessive markers + evidence-first ordering = tentative, exploratory argumentative style
• Emphatic markers + claim-first ordering + low hedging = assertive, declarative style
• High contrastive markers + dialectical ordering + concessions = nuanced, dialectical style
• High list-to-prose ratio + short paragraphs + claim-first = structured, directive style
• Low marker density + long paragraphs + narrative-embedded ordering = flowing, narrative style

Step 7: Write the Report

Write all findings to docs/analysis/20-rhetorical-discourse-structure.md.

Report Output Template

The final report MUST be written to docs/analysis/20-rhetorical-discourse-structure.md with this structure:

# Rhetorical and Discourse Structure Analysis

## Methodology
- **Approach:** Discourse marker dictionary matching, argument ordering classification, rhetorical device detection, paragraph structure measurement
- **Corpus:** [N words, N texts/documents, date range, source description]
- **Marker framework:** Fraser (1999) discourse marker taxonomy, extended with hedging categories from Hyland (2005) and Medlock & Briscoe (2007)
- **Argument ordering:** Five-pattern classification (claim-first, evidence-first, dialectical, exploratory, narrative-embedded) using signal-phrase heuristics
- **Structural analysis:** Paragraph segmentation, list detection, summary position heuristics

## Corpus Suitability Assessment
- **Word count:** [N] words ([sufficient / insufficient / marginal])
- **Multi-sentence texts:** [N] of [N] texts have 2+ sentences ([X%])
- **Paragraph structure:** [N] texts have 2+ paragraphs
- **Language:** [English / mixed]
- **Authorship:** [Single / multiple / unknown]
- **Genre:** [list genres present and their frequency]
- **Platform formatting influence:** [none / minor / significant]
- **Overall suitability:** [Suitable / suitable with caveats / unsuitable]

## Argument Ordering Distribution

| Pattern | Count | Percentage | High-Confidence Count |
|---------|-------|------------|----------------------|
| Claim-first | [N] | [X%] | [N] |
| Evidence-first | [N] | [X%] | [N] |
| Dialectical | [N] | [X%] | [N] |
| Exploratory | [N] | [X%] | [N] |
| Narrative-embedded | [N] | [X%] | [N] |
| Indeterminate | [N] | [X%] | -- |
| Too short | [N] | [X%] | -- |

**Dominant pattern:** [pattern] ([X]% of classified texts)
**Classification rate:** [X]% of texts successfully classified
**Interpretation:** [1-2 sentences on what this ordering preference reveals about argumentation habits]

## Discourse Marker Profile

### Marker Frequency by Category

| Category | Count | Rate per 1000 Words | Top Markers |
|----------|-------|---------------------|-------------|
| Contrastive | [N] | [X.X] | [marker1 (N), marker2 (N)] |
| Elaborative | [N] | [X.X] | [marker1 (N), marker2 (N)] |
| Inferential | [N] | [X.X] | [marker1 (N), marker2 (N)] |
| Topic-management | [N] | [X.X] | [marker1 (N), marker2 (N)] |
| Concessive | [N] | [X.X] | [marker1 (N), marker2 (N)] |
| Emphatic | [N] | [X.X] | [marker1 (N), marker2 (N)] |
| **Total** | **[N]** | **[X.X]** | |

**Interpretation:** [Which categories dominate? What does the ratio of contrastive-to-elaborative markers suggest about argumentative style?]

## Rhetorical Device Frequencies

| Device | Count | Rate | Level | Notes |
|--------|-------|------|-------|-------|
| Hedging (total) | [N] | [X.X] per 1000 words | [low/moderate/high] | [breakdown by type if informative] |
| Rhetorical questions | [N] | [X.X] per 100 sentences | [rare/occasional/frequent] | |
| Analogies | [N] | [X.X] per 1000 words | [rare/occasional/frequent] | |
| Concession-contrast pairs | [N] | [X.X] per 100 sentences | [rare/occasional/frequent] | |

### Hedging Detail
| Hedge Type | Count | Rate per 1000 | Examples from Corpus |
|------------|-------|---------------|---------------------|
| Modal verbs | [N] | [X.X] | [top examples] |
| Epistemic adverbs | [N] | [X.X] | [top examples] |
| Cognitive verbs | [N] | [X.X] | [top examples] |
| Approximators | [N] | [X.X] | [top examples] |
| Shields | [N] | [X.X] | [top examples] |

## Paragraph and Post Structure

| Metric | Value | Interpretation |
|--------|-------|----------------|
| Paragraph count (total) | [N] | |
| Avg paragraph length | [N] words | [short/moderate/long] |
| Median paragraph length | [N] words | |
| Paragraph length std dev | [N] | [consistent/varied/highly varied] |
| Avg sentences per paragraph | [N] | [terse/moderate/dense] |
| List paragraphs | [N] ([X%]) | [prose-dominant/mixed/list-heavy] |
| Summary position tendency | [opening/closing/distributed] | [top-down/bottom-up thinker] |

### Paragraph Length Distribution
[Histogram or frequency table of paragraph lengths by bucket: 1-20 words, 21-50, 51-100, 100+]

## Structural Writing Constraints (for Voice Replication)

| Dimension | Constraint | Derived From |
|-----------|-----------|--------------|
| Argument ordering | [e.g., "Lead with claim, then provide evidence"] | [Step 2 findings] |
| Discourse marker density | [e.g., "Use 15-20 markers per 1000 words, favoring contrastive"] | [Step 3 findings] |
| Hedging level | [e.g., "Moderate hedging; use 'I think' and 'probably' but not shields"] | [Step 4 findings] |
| Rhetorical questions | [e.g., "Use sparingly, ~1 per 500 words"] | [Step 4 findings] |
| Paragraph style | [e.g., "Short paragraphs (30-50 words), consistent length, prose-dominant"] | [Step 5 findings] |
| Summary position | [e.g., "State main point in opening paragraph"] | [Step 5 findings] |
| List usage | [e.g., "Use numbered lists for procedural content only"] | [Step 5 findings] |

## Cross-Dimension Synthesis
[Which composite style pattern does this author match? Refer to cross-dimension patterns from Step 6. Identify the 1-2 most descriptive composite labels.]

## Limitations and Caveats
- Dictionary-based discourse marker detection cannot disambiguate polysemous markers ("so" as inferential vs. filler vs. intensifier). Counts reflect maximum possible frequency; true functional frequency is lower.
- Argument ordering classification uses surface-level signal phrases, not deep semantic parsing. Classification confidence is reported per-text; low-confidence classifications should be interpreted cautiously.
- Rhetorical question detection uses syntactic patterns that may capture genuine information-seeking questions. Manual review of flagged questions is recommended.
- Hedge counts in technical or scientific corpora may reflect appropriate epistemic caution rather than a discourse habit. Genre baseline comparison is needed.
- Paragraph structure analysis depends on consistent formatting. If the corpus source strips or normalizes whitespace, paragraph metrics are unreliable.
- [Corpus-specific limitations from Step 1]
- Structural patterns are descriptive, not prescriptive. They describe what an author DOES, not what they SHOULD do or what makes writing effective.

## References
- Mann, W.C. & Thompson, S.A. (1988). Rhetorical Structure Theory: Toward a functional theory of text organization. *Text*, 8(3), 243-281.
- Fraser, B. (1999). What are discourse markers? *Journal of Pragmatics*, 31(7), 931-952.
- Lawrence, J. & Reed, C. (2019). Argument Mining: A Survey. *Computational Linguistics*, 45(4), 765-818.
- Zeldes, A. (2024). eRST: A Signaled Graph Theory of Discourse Relations and Organization. *Computational Linguistics*, 51(1), 23-90.
- Hyland, K. (2005). *Metadiscourse: Exploring Interaction in Writing*. Continuum.
- Medlock, B. & Briscoe, T. (2007). Weakly supervised learning for hedge classification in scientific literature. *ACL 2007*.
- Stab, C. & Gurevych, I. (2017). Parsing Argumentation Structures in Persuasive Essays. *Computational Linguistics*, 43(3), 619-659.
- Hutto, C.J. & Gilbert, E. (2014). VADER: A Parsimonious Rule-based Model for Sentiment Analysis of Social Media Text. *ICWSM 2014*.

Good Patterns

• Use marker dictionaries for systematic, reproducible detection -- dictionary-based counting is transparent and reproducible across analysts
• Count discourse markers by functional type, not just total count -- the ratio of contrastive to elaborative markers reveals more than total density
• Classify argument ordering patterns with explicit confidence levels -- "claim-first (high confidence)" is more useful than just "claim-first"
• Measure hedging frequency with type breakdown -- modal verbs, epistemic adverbs, cognitive verbs, and shields serve different rhetorical functions
• Analyze paragraph structure distributions, not just averages -- variance and distribution shape reveal consistency vs. situational adaptation
• Produce replicable structural constraints -- the output should be specific enough that another writer or LLM can reproduce the structural patterns
• Report marker polysemy as a limitation -- "but" counted 47 times does not mean 47 contrastive moves. Some are filler, some are elaborative.
• Cross-reference structural patterns across dimensions -- hedging frequency alone means less than hedging combined with argument ordering and concession patterns

Anti-Patterns

Boundaries

This skill SHOULD produce:

• Argument ordering pattern classifications with confidence levels for each text and aggregate distributions
• Discourse marker frequency tables by functional category (contrastive, elaborative, inferential, concessive, emphatic, topic-management) with per-1000-word rates
• Rhetorical device frequency measurements (hedging by type, rhetorical questions, analogies, concession-contrast pairs)
• Paragraph structure distributions (length, variance, list-to-prose ratio, summary position)
• Cross-dimension structural profile synthesizing all measurements into a coherent description
• Replicable structural constraints suitable for voice matching or style replication
• Written report at docs/analysis/20-rhetorical-discourse-structure.md

This skill should NOT:

• Infer intent, personality, or motivation from structural patterns alone (structure describes habits, not reasons)
• Claim that discourse analysis captures persuasive effectiveness or argument quality
• Ignore genre effects on discourse structure (academic vs. casual vs. professional produce different baselines)
• Treat structural patterns as conscious, deliberate choices by the author
• Present dictionary-based marker counts as exact functional counts (polysemy makes them upper bounds)
• Compare discourse patterns across genres without noting the genre difference
• Produce a structural profile from fewer than 500 words
• Claim that argument ordering classification is definitive (it is heuristic-based and confidence-rated)
• Substitute for deep RST parsing or manual discourse annotation (this is a scalable approximation, not ground truth)

Insufficient Data Handling

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

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

    start -> tiny [label="< 500"];
    start -> small [label="500-2,000"];
    start -> moderate [label="2,000-5,000"];
    start -> good [label="5,000+"];

    tiny_action [label="STOP: Report insufficient data.\nDo NOT classify argument ordering\nor compute structural profiles.\nReport only raw marker counts.", shape=box, fillcolor="#ffcccc"];
    small_action [label="Discourse markers and hedging\nonly. Skip argument ordering\nand paragraph structure.\nFlag LOW CONFIDENCE.", shape=box, fillcolor="#fff3cc"];
    moderate_action [label="Full analysis with\nMODERATE confidence.\nParagraph structure may be\nlimited if few multi-paragraph texts.", shape=box, fillcolor="#ffffcc"];
    good_action [label="Full analysis pipeline.\nAll features available.\nReliable structural profile.", shape=box, fillcolor="#ccffcc"];

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

Common Mistakes

References

• Mann, W.C. & Thompson, S.A. (1988). Rhetorical Structure Theory: Toward a functional theory of text organization. Text, 8(3), 243-281.
• Fraser, B. (1999). What are discourse markers? Journal of Pragmatics, 31(7), 931-952.
• Lawrence, J. & Reed, C. (2019). Argument Mining: A Survey. Computational Linguistics, 45(4), 765-818.
• Zeldes, A. (2024). eRST: A Signaled Graph Theory of Discourse Relations and Organization. Computational Linguistics, 51(1).
• Stab, C. & Gurevych, I. (2017). Parsing Argumentation Structures in Persuasive Essays. Computational Linguistics, 43(3), 619-659.
• Hyland, K. (2005). Metadiscourse: Exploring Interaction in Writing. Continuum.
• Medlock, B. & Briscoe, T. (2007). Weakly supervised learning for hedge classification in scientific literature. ACL 2007.
• Maschler, Y. (1994). Metalanguaging and discourse markers in bilingual conversation. Language in Society, 23(3).
• Open Argument Mining Framework (oAMF). ACL 2025 Demo.
• Ferrara, E. et al. (2025). Unveiling Global Discourse Structures. arXiv:2502.08371.