PRD: Docket Commenting System

Owner: Deepu Sebin

Provenance: Saved verbatim from the PRD shared over email on 22 Apr 2026 by Deepu Sebin Do not edit this file in-place; if product revises the PRD, add a new versioned file (PRD-v0.2.md, etc.) and update the index.

Status: Draft v0.1 Last updated: 22 April 2026

1. Summary

A commenting system that lets human users and AI agents leave reviewable, resolvable comments on dockets. Comments attach to the docket as a whole (not to individual blocks). The system supports three tiers of human permissions and a write-only AI agent role, enabling a structured review workflow for docket content.

2. Goals

Enable structured review and feedback on dockets across human and AI contributors.
Provide a resolution workflow so comments don’t pile up indefinitely.
Differentiate AI-generated observations from human input, visually and in data.
Enforce role-based permissions appropriate to each user type.

3. Non-goals

Block-level or inline commenting (deferred; may be considered in v2).
Real-time collaborative editing.
AI agents acting on comments - agents only write; they do not resolve, assign, or edit.
Cross-docket comment threads or linking.

4. Actors

Actor	Type	Description
Human - Type A	Human	Placeholder: e.g. Lead / Admin. Highest privilege tier.
Human - Type B	Human	Placeholder: e.g. Contributor. Standard commenter.
Human - Type C	Human	Placeholder: e.g. Limited / Reviewer. Lowest privilege tier.
AI Agent	System	Internal automated agent. Write-only.

The three human types are placeholders. The permission shapes in §6.3 can be remapped once real roles are named.

5. Core concepts

Docket. The atomic content piece in the taxonomy (L1 → L2 → L3 → Docket). The unit to which comments attach.

Comment. A single piece of feedback authored by a human user or AI agent, attached to one docket, with a lifecycle state.

Thread. The set of comments on a given docket. Whether comments support replies is a design decision - see §11.

6. Functional requirements

6.1 Comment creation

Any actor with create permission can author a comment on a docket.
Comment body supports plain text at minimum; markdown is an open question (§11).
Authorship captures author type (human / AI) and user identifier.
AI agent comments are tagged as such in data and UI.

6.2 Comment lifecycle

State	Entered by	Exit states
Open	Created	Resolved, Deleted
Resolved	Resolve action	Open (reopen), Deleted
Deleted	Delete action	- (terminal; soft delete retained for audit)

6.3 Permissions matrix

Action	Type A	Type B	Type C	AI Agent
Create comment	✓	✓	✓ (TBD)	✓
Edit own comment	✓	✓	✓	-
Delete own comment	✓	✓	✓	-
Delete any comment	✓	-	-	-
Resolve any comment	✓	✓	- (TBD)	-
Reopen any comment	✓	✓	- (TBD)	-
View all comments	✓	✓	✓	n/a

Matrix reflects an assumed permission shape; confirm once the three human types are formally defined.

6.4 AI agent behavior

Write-only. Agents post comments and nothing else.
Agent identity is distinct from any human user; each agent has a stable identifier for attribution.
Agent comments are visually marked (e.g. “AI” badge, distinct color/icon) so humans can distinguish at a glance.
Agents do not receive notifications, are not @-mentionable, and do not act on comments directed at them.

6.5 Listing, filtering, sorting

Default view: all open comments on the current docket, newest first.
Filters: status (open / resolved / all), author type (human / AI), user type (A / B / C).
Sort: by created_at ascending or descending.

6.6 Auditability

All state transitions (create, edit, resolve, reopen, delete) are logged with actor and timestamp.
Deletion is soft; record retained for audit, hidden from default view.

7. Data model (conceptual)

Comment
  id                uuid
  docket_id         uuid   → Docket
  author_id         uuid   → User | Agent
  author_type       enum { human, ai }
  author_user_type  enum { A, B, C, agent }
  body              text
  status            enum { open, resolved, deleted }
  created_at        timestamp
  updated_at        timestamp
  resolved_at       timestamp?
  resolved_by       uuid?
  parent_id         uuid?   // only if threading is in scope

8. UX requirements

Comments accessible via a panel or drawer attached to the docket view (not modal).
Count badge on the docket showing open comment count.
Clear visual distinction between AI and human comments (badge, avatar, color).
Resolve action visible to users with resolve permission; hidden otherwise.
Confirmation prompt on delete, especially for “delete any”.
Empty state when no comments exist.

9. Success metrics

Adoption: % of dockets with at least one comment in the review period.
Throughput: median time-to-resolve (created → resolved).
Quality: ratio of resolved vs. reopened comments.
AI utility: % of AI-generated comments resolved (vs. dismissed/deleted) - signals whether agent output is useful.
Engagement: comments per docket by user type.

10. Phasing

Phase 1 - MVP. Create, view, resolve, delete. Permissions enforced. AI badge. Basic list view.
Phase 2 - Workflow polish. Filters, sorts, edit history, audit log surface.
Phase 3 - Collaboration. @-mentions, notifications, threading (if approved), digest emails.

11. Open questions

Threading. Do comments support replies, or is every comment top-level? Current spec leans flat.
Body format. Plain text only, or markdown (bold, links, code)?
Attachments. Should comments support images or file attachments?
Edit window. Grace period for editing own comments, or unlimited?
AI agent triggers. What events cause an AI agent to write a comment? (On docket publish? Continuous? On demand?)
Notification system. Any notification in Phase 1 (email/in-app), or purely pull-based?
Role definitions. Finalize Type A / B / C names and permission scopes.

Reviewer notes (from email)

A couple of places worth attention during review:

§4 Actors and §6.3 Permissions - Type A/B/C are still placeholders. Once the roles are named, the permissions matrix is the main thing to revisit; the (TBD) cells are where the assumptions are shakiest.
§11, Q5 (AI agent triggers) - this determines how agents actually get invoked, and the answer could expand Phase 1 scope. Worth nailing early.
Threading - left flat (no replies) to match “docket level only”. At scale a single flat list of comments on a docket can get messy; if replies are wanted, it’s a one-field addition (parent_id) that’s cheaper to decide now than retrofit.