phy-post-forensics — "Why Did This Post Work?"#

You post 50 times. 3 go viral. 47 die. Analytics tells you "what happened" (likes, views). This tool tells you why — which structural elements in your content drove engagement.

The Problem#

Every analytics tool shows lagging indicators: impressions, likes, comments. None of them tell you:

• Which hook type correlates with your best posts?
• Do your top posts have more specific numbers?
• Does sentence rhythm (mixing short + long) predict engagement?
• Are your worst posts missing personal voice (first-person pronouns)?

This tool extracts 12 structural features per post, groups by performance tier, and outputs: "Your top posts share X, Y, Z. Your bottom posts all lack them."

Quick Start#

bash

# Analyze posts from JSON file
python3 ~/.claude/skills/phy-post-forensics/scripts/post_forensics.py --file my_posts.json

# Pipe from stdin
cat posts.json | python3 ~/.claude/skills/phy-post-forensics/scripts/post_forensics.py

# JSON output (for pipelines)
python3 ~/.claude/skills/phy-post-forensics/scripts/post_forensics.py --file posts.json --format json

Input Format#

json

[
  {
    "text": "I built 101 OpenClaw skills in 30 days. Here's what happened...",
    "platform": "linkedin",
    "engagement_rate": 8.5,
    "impressions": 15000,
    "date": "2026-03-18"
  },
  {
    "text": "Another post...",
    "platform": "reddit",
    "engagement_rate": 1.2,
    "impressions": 500
  }
]

Required: text, engagement_rate. Optional: platform, impressions, date.

The 12 Features Extracted#

#FeatureWhat It MeasuresWhy It Matters1Hook TypeFirst line classification: number_lead, question, contrarian, story_open, challenge, statementHook determines "stop scrolling" moment2Word CountTotal wordsPlatform sweet spots vary (LinkedIn ~100-200, Twitter ~50-100)3Sentence CountNumber of sentencesMore sentences ≠ better, but structure matters4Sentence Length CVCoefficient of variation of sentence lengthsHigh CV = mixed rhythm (human). Low CV = monotone (AI)5Question CountQuestions in body textQuestions drive comments and dwell time6Specific NumbersCount of data points (%, $, metrics, years)Posts with data get 3-4x more reach (LinkedIn 2026 data)7Personal Pronoun DensityI/my/we per 100 wordsPersonal voice = trust and engagement8List FormattingBullets or numbered lists presentScannability drives dwell time9Paragraph CountNumber of visual breaksShort paragraphs = mobile-friendly10CTA TypeCall-to-action classification: question, action, share, comment, noneCTAs drive comments, comments drive distribution11SentimentPositive / neutral / negative keyword analysisPositive content drives more shares12Specificity ScoreProper nouns + numbers + tool names per 100 wordsSpecific > generic (3-4x reach difference)

How Analysis Works#

1. Extract 12 features from every post
2. Tier posts by engagement: top 25%, middle 50%, bottom 25%
3. Compare feature distributions across tiers
4. Generate insights: which features differentiate top from bottom
5. Output blueprint: actionable content template based on YOUR data

Example Output#

text

==================================================================
  phy-post-forensics — Content Forensics Report
==================================================================
  Posts analyzed : 8
  Top tier       : 2 posts (avg 11.05% engagement)
  Bottom tier    : 2 posts (avg 0.40% engagement)
  Spread         : Top posts get 27.6x more engagement
==================================================================

🔍  Key Insights (8 patterns found):

  1. 🔴 [HIGH] Specific Data Points
     Top posts: 5.5 numbers/post
     Bottom:    0.0 numbers/post
     → Include specific numbers — posts with data get 3-4x reach

  2. 🔴 [HIGH] Specificity Score
     Top posts: 18.9/100w
     Bottom:    2.6/100w
     → Name specific tools, companies, projects — not generic advice

  3. 🔴 [HIGH] Hook Type
     Top posts: Mostly 'contrarian' (50%)
     Bottom:    Mostly 'challenge' (50%)
     → Lead with contrarian hooks — they correlate with your best posts

📋 YOUR CONTENT BLUEPRINT:
  HOOK: Challenge conventional wisdom: 'Stop doing X. Here's why.'
  LENGTH: ~74 words, 14 sentences
  DATA: Include ~5 specific numbers/metrics
  VOICE: Personal — aim for 2+ first-person pronouns per 100 words
  CTA: End with a clear next step the reader can take

Research Basis#

SourceKey FindingHow We Use ItBuffer 52M+ posts (2026)Dwell time > likes; specificity = 3-4x reachSpecificity scoring + feature correlationLinkedIn 360Brew dataDocument posts = 596% more engagement than text; first 150 chars criticalHook type classificationReddit 1000-post studyPosting time = 730% diff; question titles underperform by 16%Context notes in output (distribution vs content)Stanford CS229Text features + sentiment predict Reddit post popularity12-feature extraction frameworkLinkedIn 2026 benchmarks6.60% engagement for docs, 2-4% for text; 3-5 weekly optimalPlatform-aware recommendations

Collecting Your Post Data#

LinkedIn#

Export from LinkedIn Analytics → Content tab → CSV export, then convert to JSON format.

Reddit#

bash

# Use Reddit user history API
curl "https://www.reddit.com/user/USERNAME/submitted.json?limit=100" | python3 -c "
import json, sys
data = json.load(sys.stdin)
posts = [{'text': p['data']['title'] + ' ' + p['data'].get('selftext', ''),
          'platform': 'reddit',
          'engagement_rate': p['data']['upvote_ratio'] * 100,
          'impressions': p['data']['score']}
         for p in data['data']['children']]
json.dump(posts, sys.stdout, indent=2)
"

Manual#

Create a JSON file with your posts and approximate engagement rates.

Technical Notes#

• Zero external dependencies — pure Python 3.7+ stdlib
• Minimum 3 posts for meaningful analysis (8+ recommended)
• Tier grouping: top 25%, middle 50%, bottom 25% by engagement_rate
• Insight generation: only surfaces patterns with meaningful deltas (not noise)
• JSON output: --format json for pipeline integration

Companion Skills#

SkillRelationshipphy-content-humanizer-auditChecks AI signature before posting (this tool = analyzes after posting)phy-platform-rules-engineChecks platform-specific rules (this tool = analyzes content quality)phy-content-compoundBuilds content atom library (this tool = informs which atoms work best)

---

Author#

Canlah AI — Run performance marketing without breaking your brand.

• GitHub: github.com/PHY041
• All Skills: clawhub.ai/PHY041