ADR-0004: Revision Workflow

Status: Accepted

Date: 2026-01-05

Context: When an admin sees a submission that's almost right but needs changes (awkward phrasing, inappropriate detail, factual error), how do they handle it? The tension: admins need control over content, but directly editing someone else's words feels like putting words in their mouth.

Decision Drivers:

• Preserving contributor authenticity (their words, their voice)
• Admin needs ability to address problematic content
• Contributors shouldn't feel their words were changed without consent
• Workflow must be simple enough for non-technical admins

Decision

Admins cannot directly edit contributor submissions. Instead, they can:

1. Approve - Accept as-is
2. Reject - Exclude entirely
3. Request Revision - Ask contributor to modify (with notes)
4. Suggest Edits - Propose specific changes; contributor accepts or declines

This preserves the contributor's ownership of their words while giving admins tools to shape the final book.

Rationale

Tray raised the core tension: "A person shouldn't completely change the words of what another person has said. But you would want some control over what the output is."

Sheri's resolution: "I think asking for a revision... Their ability is to either completely include or completely exclude something, with the ability to ask for a revision."

Bert's addition: "We could also say, can I ask for them to revise it, or I can make a suggestion and see if they accept it."

The key insight: if the contributor accepts the edit, it becomes their words. If they don't, the admin can still reject the submission entirely. This preserves authenticity while giving admins practical control.

Considered Options

Option 1: Direct Editing by Admin

Admin can modify any submission.

Pros:

• Fast resolution
• Admin has complete control

Cons:

• Destroys authenticity
• Contributor may feel violated
• Legal/ethical concerns about attribution
• "I didn't say that" complaints

Option 2: Approve/Reject Only

Binary choice, no revision path.

Pros:

• Simple to implement
• Clear ownership

Cons:

• Loses good content with minor issues
• All-or-nothing is frustrating
• Contributors may not know why rejected

Option 3: Request Revision + Suggest Edits (Selected)

Admin can request changes or propose specific edits; contributor decides.

Pros:

• Preserves authenticity
• Collaborative process
• Contributor retains ownership
• Admin has practical control (can still reject if no agreement)

Cons:

• More complex workflow
• Requires contributor re-engagement
• Mitigation: Email notifications, deadline for response

Consequences

Positive

• Contributor words remain their own
• Collaborative relationship between admin and contributors
• Higher quality final output
• No "I didn't write that" disputes

Negative

• Longer time to finalization (waiting for responses)
• Mitigation: Set response deadlines; auto-exclude if no response
• More emails/notifications
• Mitigation: Batch notifications, configurable frequency

Neutral

• Adds complexity to Phase 2 development
• This is Phase 2 functionality (not MVP)

Implementation

Phase 1 (MVP):

• Approve/Reject only
• Rejection includes optional note to contributor

Phase 2:

• Request Revision workflow

  • Admin adds note explaining requested changes
  • Contributor receives email
  • Contributor submits revised version
  • Original preserved for reference

• Suggest Edits workflow

  • Admin proposes inline changes (track-changes style)
  • Contributor sees diff
  • Contributor accepts/declines each suggestion
  • Accepted suggestions become contributor's words

Database Model:

Submission {
  ...
  status: enum('pending', 'approved', 'rejected', 'revision_requested', 'revision_submitted')
  admin_notes: text (nullable)
  revision_history: json[] (array of previous versions)
}

SuggestedEdit {
  submission_id: FK
  original_text: text
  suggested_text: text
  status: enum('pending', 'accepted', 'declined')
  admin_id: FK
  created_at: timestamp
}

Files Affected:

• Submission model
• Admin review interface
• Contributor notification system
• Diff/track-changes UI component

Related Decisions

• ADR-0001: AI Assistance Philosophy (AI suggestions vs admin suggestions)
• ADR-0002: Editorial Control Model

References

• 20260105-napkin-session.md - "Tension" discussion with Tray

Author: Bert Carroll Reviewers: Sheri Dudley, Tray Turner Last Updated: 2026-01-05