GPT Review — 23-P3C Functions Prompt rev1 + Natural UX Directive

Date: 2026-05-07
Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI
Reviewed: knowledge/dev/laws/dieu44-trien-khai/prompts/23-p3c-iu-edit-draft-functions-prompt.md rev1

Verdict

Rev1 has the right philosophy but is NOT ready to dispatch. Rev2 required.

Opus correctly captured the User’s key design principle:

A good design is one where Agents do not need to remember the process. The operation must be as natural as an iPhone interface: obvious, guided, and difficult to misuse.

However, rev1 currently swings too far from safety into convenience in one place, and it is too under-specified for a production function pack in another place.

Analysis of Opus’s pushbacks

Pushback 1 — Rename natural comment helper to fn_iu_comment

Accepted.

fn_iu_comment is better than fn_iu_comment_current_draft for Agent UX. It names the natural action, not the implementation detail.

Keep both layers:

• fn_iu_comment_edit_draft(...) = exact low-level function by draft_id;
• fn_iu_comment(...) = natural high-level function by canonical_address.

This matches the User’s requirement: Agents can simply “come in and give an opinion.”

Pushback 2 — Multiple open drafts should attach to latest, not return ambiguous

Partially rejected.

The goal is not merely “no need to remember.” It is:

1. no need to remember the process;
2. cannot accidentally do the wrong thing.

Automatically attaching to the latest open draft can be wrong. Example:

• GPT creates draft A;
• Gemini creates draft B later;
• Opus says “I agree with GPT’s approach” and calls fn_iu_comment(address, ...);
• system silently attaches to Gemini’s later draft B.

That is simple, but it is not safe. It violates “không thể làm nhầm được.”

GPT replacement design: guided safe default

fn_iu_comment(address, actor, body) should behave as follows:

• 0 open drafts → no_open_draft + guidance.
• 1 open draft → attach automatically.

• 1 open draft → do not guess silently. Return multiple_open_drafts with:

  • candidate draft IDs;
  • created_by;
  • created_at;
  • reason/title preview;
  • hash preview;
  • guidance: “Use fn_iu_comment_edit_draft(draft_id, ...) or pass selector metadata.”

To keep “no need to remember” as much as possible, add an optional selector/context input:

fn_iu_comment(p_address text, p_author text, p_body text, p_kind text DEFAULT 'general', p_author_type text DEFAULT 'agent', p_context jsonb DEFAULT '{}'::jsonb)

Resolution rules:

• if p_context->>'draft_id' is provided → attach to that draft after validating it belongs to address;
• else if exactly one open draft → attach;
• else if multiple open drafts and p_context->>'select' = 'latest' → attach latest and state selected_by='latest';
• else return multiple_open_drafts with candidates.

This keeps the interface simple while preventing silent wrong attachment. The AI does not need to know the whole process; when the situation is ambiguous, the response itself teaches the next command.

Pushback 3 — Self-guiding responses

Accepted and strengthened.

Every non-success status must include guidance and ideally next_action.

Examples:

• no_open_draft: next_action='fn_iu_edit'
• multiple_open_drafts: next_action='fn_iu_comment_edit_draft'
• stale_base: next_action='fn_iu_create_edit_draft'
• draft_not_open: next_action='inspect_draft_or_create_new'

Critical prompt issue: Agent must not “write SQL bodies freely”

Rev1 says:

Agent tự viết SQL bodies dựa trên specifications. Không copy-paste — adapt theo runtime convention discovered.

This is too loose for a production function pack. P3C creates core write-path functions. We cannot rely on an execution Agent improvising bodies from prose.

Rev2 should either:

1. be a design prompt only, not execution; or
2. provide self-contained executable SQL skeletons/bodies with clearly marked runtime-discovered constants.

Given Pack 22 quality standard, GPT recommendation:

• Rev2 remains an execution prompt, but must be much more deterministic:
  • exact function signatures;
  • exact status vocabulary;
  • exact validation behavior;
  • exact transaction/exception behavior;
  • SQL bodies or near-complete bodies;
  • explicit places where Agent may adapt based on preflight.

If Opus feels exact bodies are too long, split P3C into smaller packs:

• P3C1: plan + create draft + low-level/natural comment functions;
• P3C2: apply + wrapper functions.

This may be safer than a giant all-in-one pack.

Required rev2 patches

P1 — Keep fn_iu_comment, but make ambiguity safe

Patch natural comment helper:

• keep name fn_iu_comment;
• add p_context jsonb DEFAULT '{}'::jsonb;
• support explicit draft_id in context;
• attach automatically only when exactly one open draft;
• if multiple open drafts and no explicit selector, return multiple_open_drafts with candidates and guidance;
• if p_context->>'select'='latest', attach latest and report selected_by='latest'.

Do not silently attach latest by default.

P2 — Strengthen “Apple/iPhone” UX principle

Add section:

Agent UX Contract — Simple but Safe

Rules:

• one obvious high-level function per intent;
• no Agent needs to know table names, version_seq, hash, gateway marker, anchor, or birth;
• if exactly one safe action exists, do it;
• if multiple possible targets exist, do not guess silently;
• return guided next action;
• low-level functions exist for reviewer/advanced flows.

P3 — Add status vocabulary table

Define allowed statuses for all functions. Example:

• plan_ok
• invalid_input
• iu_not_found
• no_head_version
• no_change
• draft_created
• comment_added
• no_open_draft
• multiple_open_drafts
• draft_not_found
• draft_not_open
• stale_base
• applied
• policy_require_review
• invariant_failed

Each status should have required fields and guidance.

P4 — Split P3C if needed

Opus should decide between:

Option A: keep one P3C prompt but make it self-contained enough for safe execution.

Option B, GPT-preferred for safety: split into two prompts:

• P3C1: fn_iu_edit_plan, fn_iu_create_edit_draft, fn_iu_comment_edit_draft, fn_iu_comment.
• P3C2: fn_iu_apply_edit_draft, fn_iu_edit wrapper.

Reason: apply/wrapper are the only functions that write IU/UV and use gateway. Draft/comment are lower-risk and can be verified before apply.

P5 — Do not let Agent infer lifecycle convention loosely

Rev1 says Agent should read source and determine convention. That is acceptable as a preflight, but execution must have a deterministic rule:

• inspect current UV rows;
• if all existing UV rows share one lifecycle_status, use that exact value;
• if mixed values, inspect fn_iu_create source and report;
• if still unclear, STOP for GPT/User decision.

Do not let Agent choose creatively.

P6 — Exact signatures should be specified

Rev2 must list exact proposed signatures. For example:

• fn_iu_edit_plan(text,text,text,text,text) or named signature with defaults;
• fn_iu_create_edit_draft(text,text,text,text,text);
• fn_iu_comment_edit_draft(uuid,text,text,text,text);
• fn_iu_comment(text,text,text,text,text,jsonb);
• fn_iu_apply_edit_draft(uuid,text,text);
• fn_iu_edit(text,text,text,text,text).

Use defaults where helpful, but make exact signatures clear for REVOKE/GRANT/tests.

P7 — Permission/grant role must be discovered, not assumed

Use Pack 22 pattern, but preflight must discover intended execute role(s). If only directus has EXECUTE on Pack 22 functions, grant new functions to directus only. Report if expected role missing.

P8 — Tests must cover no-silent-wrong-comment

Add tests:

• one open draft → fn_iu_comment attaches automatically;
• two open drafts → fn_iu_comment returns multiple_open_drafts, does not insert comment;
• two open drafts + context {draft_id: ...} → attaches to selected draft;
• two open drafts + context {select:'latest'} → attaches latest and reports selected_by='latest'.

This directly verifies the “simple but cannot do wrong” principle.

P9 — Tests should separate low-risk P3C1 from apply P3C2 if split

If Opus chooses split, P3C1 tests must prove:

• plan no-write;
• create draft;
• comment low-level;
• comment natural safe resolution;
• no IU/UV changes.

P3C2 tests then prove:

• apply creates UV;
• wrapper auto-apply;
• stale base;
• invariant verify;
• gateway marker.

P10 — Report must include UX evidence

Report should include a section:

Agent UX / Self-guiding evidence

Show sample JSON outputs for:

• success;
• no open draft;
• multiple open drafts;
• stale base;
• invalid input.

Directive to Opus

Patch P3C prompt to rev2.

Path:

knowledge/dev/laws/dieu44-trien-khai/prompts/23-p3c-iu-edit-draft-functions-prompt.md

Apply P1–P10.

Do not dispatch after patch. Return for GPT/User review.

Hard boundaries remain

• No dispatch.
• No table DDL.
• No schema changes.
• No trigger changes.
• No gateway changes.
• No vector mutation.
• No cleanup.
• No Pack 2C.

Summary

Opus correctly captured the natural UX philosophy and fn_iu_comment naming. But “always attach latest” is too risky because the user also requires “cannot do wrong.” The right balance is guided safe default: auto-attach only when unique; otherwise return a self-guiding response with candidates or require explicit context. Also, P3C is core behavior and should not leave SQL bodies to Agent improvisation.