GPT Note — Pack 23 Natural Comment UX Requirement

Date: 2026-05-07
Context: User clarified requirement while P3B Agent execution is running.

Requirement to remember for P3C

A good design is one where nobody has to remember the process.

For the IU edit/comment workflow, AI/Agents should be able to comment naturally without knowing the schema or workflow details.

The user expectation:

User chỉ cần giao: “vào có ý kiến về việc này.”
AI/Agent có thể thoải mái comment theo cách họ nghĩ là đúng.
Hệ thống tự động gắn comment vào đúng draft/context, lưu tên người comment, loại actor, thời gian, kind/defaults.
Người/chính/Opus được giao phê duyệt mới cần hiểu hoặc thực hiện apply/edit cuối theo lệnh user.

Design implication

P3C function design must include a natural comment interface. The Agent should not need to remember:

• draft/comment table names;
• draft_id if context can resolve it;
• author_type enum;
• comment_kind enum;
• timestamps;
• status rules;
• whether draft is open/stale/applied;
• direct INSERT rules.

The system should fill defaults and validate.

Required P3C design hook

When designing comment functions, include at least two layers:

1. Low-level exact function:

   • fn_iu_comment_edit_draft(p_draft_id, p_author, p_comment_body, p_comment_kind DEFAULT 'general', ...)

2. Natural/context helper if feasible:

   • fn_iu_comment_current_draft(p_canonical_address, p_author, p_comment_body, p_comment_kind DEFAULT 'general', p_context DEFAULT NULL)
   • or equivalent function that resolves the active/open draft for an IU/address.

Resolution policy should be explicit:

• if exactly one open draft for address → attach comment automatically;
• if multiple open drafts → return ambiguous_draft with candidate draft IDs/summaries;
• if no open draft → return no_open_draft and optionally suggest creating a draft first;
• if draft_id is provided → attach directly.

Do not silently attach to the wrong draft.

Defaults

• author_ref required, but function can accept actor text and set author_type='agent' by default.
• comment_kind default = general.
• created_at = now().
• metadata default = {}.
• comments append-only.

Principle

This mirrors the Pack 22 birth philosophy:

• Agent should not remember birth/version/anchor in create flow.
• Agent should not remember draft/comment workflow in comment flow.
• System should either do the right thing or return a precise action-required status.

Add to next Opus directive

When P3B execution report is reviewed and P3C planning starts, explicitly instruct Opus to include this natural comment UX requirement.