v5-json-contract-change

3 min read

V5 JSON Contract Change — Dev Spec

Status: Proposed (pending Rahul’s approval) Scope: Additive changes to the input and output JSON of the unified Reddit commenting RPA flow. Related prompts: reddit-comment-system-prompt-v4-unified.md, reddit-comment-user-prompt-v4-unified.md Purpose: (1) Give the AI the top 2 comments on a post as context so it can compete with what’s already winning. (2) Add a strategy_used output field so we can measure which comment strategy actually earns upvotes per subreddit.

1. INPUT JSON (backend → AI)

Before (v4) — 12 fields

{
  "subreddit": "sales",
  "post_title": "...",
  "post_content": "...",
  "post_age_minutes": 45,
  "existing_comments": 12,
  "post_author": "username",
  "post_type": "text",
  "profile_username": "hailybarnes37",
  "profile_karma": 180,
  "profile_age_days": 52,
  "profile_timezone": "EDT",
  "current_hour": 14
}

After (v5) — 13 fields (1 new: top_comments)

{
  "subreddit": "sales",
  "post_title": "...",
  "post_content": "...",
  "post_age_minutes": 45,
  "existing_comments": 12,
  "post_author": "username",
  "post_type": "text",
  "profile_username": "hailybarnes37",
  "profile_karma": 180,
  "profile_age_days": 52,
  "profile_timezone": "EDT",
  "current_hour": 14,
 
  "top_comments": [
    {
      "score": 482,
      "body": "full top comment (by highest no of upvotes) text"
    },
    {
      "score": 210,
      "body": "full top comment (by 2nd highest no of upvotes) text"
    }
  ]
}

Rules for top_comments

RuleDetail
SelectionTop 2 comments by score on the post (not newest)
Empty case[] (empty array) when the post has fewer than 2 comments
Existing fieldsAll 12 unchanged — no renames, no type changes, no removals

2. OUTPUT JSON (AI → backend)

Before (v4) — SAFE response, 10 fields

{
  "action": "SAFE",
  "categories": ["category1"],
  "confidence_scores": {"category1": 0.65},
  "sensitive": false,
  "comment": "the comment text",
  "word_count": 24,
  "subreddit_template_used": "r/sales",
  "upvote_triggers": ["make_them_think", "make_them_nod"],
  "quality_score": 8,
  "quality_notes": "note"
}

After (v5) — SAFE response, 11 fields (1 new: strategy_used)

{
  "action": "SAFE",
  "categories": ["category1"],
  "confidence_scores": {"category1": 0.65},
  "sensitive": false,
  "comment": "the comment text",
  "word_count": 24,
  "subreddit_template_used": "r/sales",
  "upvote_triggers": ["make_them_think", "make_them_nod"],
  "quality_score": 8,
  "quality_notes": "note",
 
  "strategy_used": "quote_rebuttal"
}

Allowed values for strategy_used

ValueMeaning
new_angleTop comment was strong; added a different angle with new info
contrarian_takeTop comment was consensus; pushed back with a take the community would side with
quote_rebuttalQuoted a phrase from the top comment, delivered a counter
post_onlyNo top_comments provided (post had < 2 comments) — generated from the post alone

SKIP response — unchanged (4 fields, no strategy_used)

{
  "action": "SKIP",
  "reason": "...",
  "categories": ["category1"],
  "confidence_scores": {"category1": 0.85}
}

3. Summary

v4v5Breaking?
Input fields1213 (+top_comments)No — additive
Output fields (SAFE)1011 (+strategy_used)No — additive
Output fields (SKIP)44No — unchanged

Backend work required:

  1. Fetch the top 2 comments by score for the post (alongside the existing post fetch).
  2. Inject as top_comments in the user message JSON.
  3. Log strategy_used in the metrics DB alongside the existing fields (for the feedback loop).

Both changes are additive only — old fields keep their exact names, types, and meaning. The backend can ship v5 without touching anything that exists today.

Source: RPA comment similarity analysis (post 1vkwaca) + 1,748-comment ICP analysis. See growreach-reddit-strategy/growreach-comment-analysis/post_1vkwaca_similarity_report.md.

Graph View