Skip to content

PLAN.md

Latest commit

 

History

History
313 lines (225 loc) · 8.74 KB

PLAN.md

File metadata and controls

313 lines (225 loc) · 8.74 KB
Raw

PLAN.md — ModMirror Build Plan

Goal

Build ModMirror, a Devvit moderation app that helps Reddit moderator teams find and reduce enforcement inconsistency.

Core pitch:

ModMirror finds enforcement drift before your users do.

Product Positioning

ModMirror is not:

  • a queue dashboard,
  • a Toolbox clone,
  • a strike bot,
  • an AI moderator,
  • a replacement for human judgment.

ModMirror is:

  • a moderation consistency layer,
  • a policy agreement tool,
  • a guided enforcement workflow,
  • an audit trail for exceptions and drift.

MVP Scope

The MVP has four core pieces:

  1. Mirror Scan
  2. Policy Agreement Flow
  3. Apply Policy Action
  4. Consistency Nudge + Override Audit

Everything else is out of scope until these work.

Wave 0 — Research + Scaffold Proof

Objective

Kill platform uncertainty before product implementation.

Must answer in RESEARCH.md

  1. What Devvit version/package shape is generated by the current template?
  2. What is the exact project structure?
  3. What permissions are required in devvit.json for:
    • Reddit API access
    • Redis
    • menu actions
    • triggers if needed
  4. Does getModerationLog() exist in the installed SDK?
  5. What does getModerationLog() return?
  6. Does it include removal reason/rule metadata?
  7. Does getSubredditRemovalReasons() exist?
  8. Does it return ID, title, and message?
  9. Does a subreddit rules API exist?
  10. Can a post/comment menu action trigger a form?
  11. Can a form chain to another form?
  12. Can a menu action access the target post/comment ID and author?
  13. Can the app submit a comment to a removed post/comment thread?
  14. If not, must the comment be submitted before removal?
  15. Can the app send private messages?
  16. Can the app add native Mod Notes?
  17. Can the app detect moderator permissions for current user?
  18. Does playtest work in the target test subreddit?
  19. What are the exact commands for dev, upload, and publish in this generated project?

Deliverables

  • Devvit app scaffold or verified template.
  • Minimal dashboard endpoint/page. Wave 0 outcome: non-destructive smoke endpoints exist; generated template has no client dashboard entry yet.
  • Redis smoke test.
  • Reddit API smoke test.
  • Menu action smoke test if feasible.
  • RESEARCH.md completed.
  • TODO.md updated.

Acceptance Criteria

  • npm install works.
  • npm run dev or current generated dev command works far enough to identify playtest/auth blockers.
  • App can be playtested after Devvit auth/app binding is completed; Wave 0 did not complete runtime playtest.
  • RESEARCH.md answers every Wave 0 question with evidence or limitation.
  • Any failed assumption is clearly documented.

Wave 0 Outcome

Local scaffold, typecheck, lint, build, test, and SDK/type research succeeded. Runtime playtest, Redis runtime proof, Reddit API runtime proof, menu/form UX proof, comment delivery ordering, modmail/private message behavior, native Mod Notes behavior, and exact moderator permission strings remain unverified.

Wave 1 — App Skeleton + Data Contracts

Objective

Create the stable internal structure that all future waves use.

Wave 0 Reality To Preserve

  • The current scaffold is Devvit Web with Hono server routes; it does not yet include a generated client dashboard entry.
  • npm run dev runs devvit playtest and remains blocked until Reddit CLI auth/app binding is completed.
  • Reddit SDK support is type/build-verified locally, but live Reddit/Redis/menu/form behavior is not playtest-verified.
  • Policies must use local derived rule keys because the installed subreddit Rule type does not expose a stable rule ID.
  • Historical mod-log attribution must be inferred with confidence because ModAction does not expose structured rule/removal reason fields.
  • Message delivery must default to log_only until public comment behavior before/after removal is playtest-verified.

Deliverables

  • src/shared/schema.ts
  • src/shared/constants.ts
  • server route structure
  • Redis key helper
  • basic dashboard shell/client entry
  • demo mode flag
  • health endpoint
  • typed API response shapes

Acceptance Criteria

  • Typecheck/build passes.
  • Dashboard shell loads if the Wave 1 client entry is present; otherwise health/status routes must make the missing client explicit.
  • Health endpoint returns app/subreddit context if available and clearly labels missing playtest proof.
  • Redis key helper is used everywhere.

Wave 2 — Mirror Scan + Attribution

Objective

Implement first-run scan and deterministic rule attribution.

Deliverables

  • Fetch mod log.
  • Fetch removal reasons.
  • Fetch subreddit rules if available.
  • Normalize actions.
  • Attribution scoring:
    • exact match
    • fuzzy/simple similarity
    • keyword overlap
    • fallback unmatched
  • Confidence scoring.
  • Drift summary.
  • Demo seed scan.

Acceptance Criteria

  • Real scan works on test subreddit, even if sparse.
  • Demo scan shows meaningful drift.
  • Dashboard displays:
    • scanned actions
    • attributed actions
    • confidence breakdown
    • unmatched actions
    • drift candidates
  • No inferred rule is presented as certain unless confidence is high.

Wave 3 — Policy Agreement Flow

Objective

Allow mods to create/edit policy ladders per rule.

Deliverables

  • Policy editor UI.
  • Create policy from drift candidate.
  • Create policy manually.
  • Empty policy fallback.
  • Store policies in Redis.
  • Small subreddit mode.

Acceptance Criteria

  • A mod can create a policy for a rule.
  • A mod can edit a policy.
  • A rule with no policy routes to creation flow.
  • Small subreddit/no-data state is useful, not empty.

Wave 4 — Apply Policy Action

Objective

Allow mods to apply a policy to a post/comment.

Deliverables

  • Post/comment menu item.
  • Select rule/policy.
  • Show recommendation.
  • Confirm action.
  • Public comment/private message/log-only delivery mode if verified.
  • Store action event in Redis.

Acceptance Criteria

  • Menu action appears only for moderators if possible.
  • Target post/comment context is captured.
  • Recommended action is shown.
  • Confirmed action is logged.
  • Delivery behavior is stable and documented.

Wave 5 — Governance Core

Objective

Close the governance loop after policy application by preserving policy history, reviewing exceptions, and surfacing deterministic policy health.

Deliverables

  • Immutable policy version history.
  • Active version pointer for each policy.
  • Action and override logs stamped with the active policy version/snapshot.
  • Override review inbox with unresolved/reviewed statuses.
  • Deterministic policy health scoring:
    • stable
    • watch
    • at_risk
    • needs_review
    • insufficient_data
  • Governance dashboard showing health cards, review inbox, and version summary.

Acceptance Criteria

  • Policy edits create new versions without deleting older versions.
  • Apply Policy logs include policy version context when available.
  • Overrides default to unresolved and can be reviewed.
  • Policy health works for real, demo, and sparse data without AI/LLMs.
  • Dashboard exposes health, inbox, and version data without per-mod blame.

Wave 6 — Case Packet / Appeal Context

Objective

Use the governance data from Waves 1-5 to build a focused case context view for appeals and moderator review. Do not add digest/scheduler or AI judging.

Deliverables

  • Case Packet / Appeal Context view for a single target/user/rule.
  • Policy version active at action time.
  • Relevant action and override history.
  • Clear confidence labels for inferred historical attribution.
  • Human-readable context for moderator review.
  • README/submission polish after runtime proof.

Acceptance Criteria

  • Case context is explainable without becoming an AI judge.
  • No automatic enforcement or digest scheduler is introduced.
  • Demo mode still works.
  • Submission copy stays within verified behavior.

Deferred Features

Do not build unless MVP is complete:

  • full appeal packet generator,
  • complex queue dashboard,
  • AI rule classifier,
  • automatic bans,
  • cross-subreddit benchmarking,
  • Discord/Slack integrations,
  • LLM summaries,
  • external analytics service.

Risks

Rule Attribution Risk

Historical mod logs may not contain structured rule IDs.

Mitigation:

  • deterministic matching,
  • confidence levels,
  • manual confirmation,
  • demo seed mode,
  • track ModMirror-created actions going forward.

Devvit UX Risk

Menu action flows may be constrained.

Mitigation:

  • dashboard for rich analysis,
  • forms for quick actions,
  • document limitations in RESEARCH.md.

Small Subreddit Risk

Low volume may make drift analysis weak.

Mitigation:

  • policy-first mode,
  • minimum thresholds,
  • demo mode,
  • “prevent future drift” framing.

Submission Risk

Judges may not deeply install the app.

Mitigation:

  • polished screenshots,
  • seeded demo,
  • clear video narrative,
  • strong Devpost copy.