RFC Review: Autonomous AI Agent Phase 2 — AI-Assisted Refinement

Companion review for phase-2-ai-assisted-refinement.md, produced by the rfc-reviewer skill. Lives beside the RFC; valid only for the RFC revision in reviewed_rfc_last_updated (2026-07-07 / 15aa71d). This is review cycle R1 — no prior review existed.

Executive Summary

• Overall Score: 8.5/10
• Rating: Agentic-Ready
• RFC Type: full-stack
• Sub-Type: new-feature (FE) + new-feature (BE)
• Assessment Confidence: High
• Applied Caps/Gates: none — every category ≥ 7.5; ACV/DIC/FMC/CNT all ≥ 8.5; deploy order specified; no cross-layer contract mismatch found
• Implementation Readiness Verdict: PROCEED with notes — Chunks 1–8 are executable against the documented contract + a stub today; the real-upstream pass (Chunk 9) and end-to-end acceptance are gated on an external dependency the RFC honestly flags (OQ-1a: upstream refine-skill-pack deployment/gateway exposure unverified), not on any spec gap.
• Report Path: chatbot/autonomous-ai-agent/rfcs/phase-2-ai-assisted-refinement-review.md
• RFC Author: Dimas Fauzi Hidayat (PM), Eng co-author Eko Aprianto | Reviewed: 2026-07-08

Yes — an AI agent can read this RFC and produce correct implementation code for the backend proxy, the shared-builder extraction, and the Refine rail without a clarification meeting, for the ~90% of the work that does not touch the still-unverified upstream. This is one of the most rigorously grounded RFCs I have reviewed: I checked ~60 file:line / symbol / contract claims against the real chatbot, chatbot-fe, and qontak-designer working trees and every symbol, pattern, contract, and behavior it cites is real — the reconciliation notes, the "as-built" upstream contract, the surgical-patch guarantee, the stateless-BE decision, and the reuse-the-existing-PATCH apply path are all correct and internally consistent. The biggest strength is decision closure: 10/10 major decisions are Resolved with alternatives, rationale, consequences, and reversibility, each grounded in named code. The biggest gap is not in the spec but in the world: the feature is a thin proxy in front of a Data/ML endpoint whose deployment is unverified, and two genuinely open behavioral questions (OQ-11 multi-turn context carry-through, OQ-4 KB-patch policy) could cause rework. The one thing to fix before an agent runs the Reading Guide by line: the line-number citations have drifted since the 2026-07-05 grounding pass (notably AiAgentEditor.vue, now off by ~+85 lines) — symbols are correct, so a grep-first agent recovers, but the numbers are stale.

---

Quick Verdict

Why this RFC can be implemented agentically:

• Every contract is pinned to real code: full BE↔FE request/response JSON (§2.4), TS interfaces with props/emits (§2.A), the exact seam for the shared-builder extraction (Decision 3), and a 9-chunk execution plan with per-chunk verifiable acceptance criteria and the actual bundle exec rspec / pnpm commands (§4.D, §4.C).
• Failure handling is exhaustive and cross-layer-consistent: §3.A failure catalog, §3.A.1 branch catalog, §3.B/§3.C BE+FE error catalogs, and dedicated failure-path sequence diagrams. All 11 Mermaid diagrams parse.
• Scope is bounded to the file: §2.I lists files to create, to modify (with reasons), and explicitly NOT to touch on both layers.

Why this RFC will cause agent guessing or rework:

• The whole feature proxies an upstream endpoint that is documented but not verified deployed (OQ-1a) — an agent can build against the stub but cannot complete Chunk 9 or prove end-to-end behavior.
• Line-number citations are stale (AiAgentEditor.vue ~+85, prototype ~+18) and two BE helper/middleware paths are one directory level off — an agent trusting the Reading Guide's exact lines lands in the wrong place.
• The updated_capability_pack → real form-model field/label map (the FE differ + applyPendingData port) is deferred to implementation, and OQ-11 leaves the multi-turn context mechanism unconfirmed.

---

Findings Ledger (carry-forward)

ID	Severity	Finding (one line)	RFC location	Status	First seen	Resolved in	Evidence / fix
REV-1	major	Line-number citations drifted since authoring — AiAgentEditor.vue off ~+66…+86, prototype ~+18	§2.0 Reading Guide / Source Verification / Design↔Code; §2.A	open	R1	—	Verified vs real repos: showPreview :3015→:3081, activeTab.value=2 :3652→:3738, handleSave :3692→:3778, file 5,416→5,529 lines; prototype rightRailTab :4066→:4084, ProposedChange :4021→:4039, .recommended-border-anim :9318→:9422. Symbols correct → grep-first agent recovers. Fix: re-ground numbers or cite by symbol + note these files drift.
REV-2	minor	Two BE paths point one directory too deep	§2.0 Source Verification (rows for authorization_helpers / ownership)	open	R1	—	set_role/403 lives at app/api/frontend_service/helpers/authorization_helpers.rb:6–10 and Ownership at app/api/frontend_service/middlewares/ownership.rb:7 (shared FE-service scope), not under v2/ai_agent/{helpers,middlewares}/. Symbols/behavior correct. Fix: correct the two paths.
REV-3	major	Core upstream dependency documented "as built" but deployment/gateway exposure UNVERIFIED	§1 Dependencies; §2.4; §5 OQ-1a; §7	open	R1	—	RFC's own §7 execution blocker. Chunks 1–8 unblocked; Chunk 9 real-upstream + end-to-end acceptance blocked. External gate, not a spec defect. Owner PM+Data/ML, due 2026-07-15.
REV-4	major	Multi-turn context carry-through unconfirmed against single-POST upstream design	§5 OQ-11; REFINE-S03/AC-1; §2.B	open	R1	—	RFC specifies flat re-send of last-10 chat_history, but OQ-11 openly doubts whether a follow-up ("now also handle the timeout case") actually carries prior-turn context. Agent builds the specified flat re-send; satisfying S03/AC-1 is unverified. Fix: confirm chat_history semantics/bounding with Data/ML before Chunk 9.
REV-5	minor	KB-affecting-patch policy on Apply undecided	§5 OQ-4; REFINE-S02 apply path	open	R1	—	Allow vector re-resolve vs reject KB-affecting patches is a product decision due before Closed Beta; doesn't block Chunks 1–8 but S02 apply behavior for a KB-referencing patch is unspecified until then. Also needs Data/ML to confirm which patches refine can even emit.
REV-6	minor	updated_capability_pack → real form-model field/label map deferred to implementation	§2.A; §2.0 Design↔Code (Accept→stage row)	open	R1	—	The FE differ + applyPendingData port names the sources (useAgentStore.ts:79–86 AgentDetailConfig + prototype applyPendingData) but tabulates no explicit field/label map — the single largest "agent figures it out" surface. Derivable, but rework-prone. Fix: add an explicit field-map table to Detail 2.A.
REV-7	minor	Internal staleness — two spots still say REFINE-S01/AC-4 "needs PRD correction" after the PRD was corrected	§1 Detail 1.A (AC-4 row); §3.A.1 branch catalog	open	R1	—	PRD v1.5/v1.5.1 already rewrote AC-4 to the as-built surgical-patch guarantee; the §1 reconciliation row correctly says "Corrected in PRD v1.5," but Detail 1.A and the branch catalog still read "AC-4 needs PRD correction." Fix: update both to "corrected in PRD v1.5.1."

Ledger summary: 7 open (0 blocker, 3 major, 4 minor), 0 fixed this cycle (first cycle), 0 accepted-risk. All still-open material findings are promoted to the RFC Open-Questions surface below by id. Note REV-3/REV-4/REV-5 already correspond to existing RFC OQ-1a/OQ-11/OQ-4 — this review confirms and cross-references them rather than minting parallel work.

---

PRD → RFC Traceability Matrix

Source PRD: ../prds/phase-2-ai-assisted-refinement.md (v1.5.1). The RFC carries a full bidirectional matrix in Detail 1.A + a per-story change map in Detail 1.C + a PRD-section coverage table. Verified complete.

PRD Element	RFC Section	Coverage
REFINE-S01/AC-1..4, ERR-1..2 (refine in natural language)	Detail 1.A; §2.4; §2.A; §2.C	Full
REFINE-S02/AC-1..3, ERR-1..2 (accept + save)	Detail 1.A; §2.A; §2.H flow 2; §2.D/2.E	Full
REFINE-S03/AC-1..3, ERR-1 (multi-turn)	Detail 1.A; §2.B; §2.4 chat_history	Full — but AC-1 (context-aware follow-up) rests on OQ-11, mechanism unconfirmed (REV-4)
REFINE-S04/AC-1..3, ERR-1 (config audit)	Detail 1.A; §2.4 "Config-audit turns"; success criterion 6; §4.C staging scenario	Full — reliability rests on OQ-1g (upstream complaint-free audit tuning)
REFINE-S01-NEG/NEG-1..2 (no legacy refine; no auto-apply)	Detail 1.A; §2.4 status codes; §3.A.1	Full
PRD §10 API placeholder ("resolved in RFC §2.4")	§2.4	Full — schemas resolved
PRD §12.1 semantic rollback (PaperTrail revert)	§4.E rollback recipe step 2	Full
PRD §13 events	§3 Monitoring (mapped to Mixpanel + Rails.logger/Rollbar — no BE event bus exists, correctly reconciled)	Full

Summary: 8 of 8 PRD story/rule groups fully covered, 0 partial, 0 missing. 0 RFC decisions without a PRD driver (scope is a strict subset of PRD §7). No FE↔BE scope contradiction found. One cross-artifact drift (REV-7): two RFC cells still say AC-4 "needs PRD correction" though the PRD already corrected it — the direction of drift is harmless (RFC is stricter/older-worded), but the internal inconsistency should be cleaned.

---

Scorecard

Full-Stack Scorecard (18 categories)

#	Category	Source	Score	Evidence-Based Rationale
1	PRT — PRD Traceability	Merged	9.0	FE+BE: Detail 1.A forward+reverse, 1.C per-story change map, PRD §-coverage table; all 5 stories + composite ACs mapped; no cross-layer contradiction.
2	TDC — Technical Decisions	Merged	9.0	10-row decision index (1.B) + 7 full ADR blocks with options/rationale/consequences/reversibility; cross-layer decisions (options[] shape ADR-6, diff source ADR-7) resolved; each grounded in named code.
3	CNT — Contract Specificity	FE	8.5	§2.A full TS interfaces (RefinePanelProps, RefineMessage, RefineOption, ProposedChange, RefinePendingData), emits, state ownership. Docked: field/label + pendingData→form-model map deferred (REV-6).
4	SCB — Scope Boundaries	FE	9.0	§2.I explicit create / modify (+reason) / NOT touched for both layers; shared-file impact called out (sync_to_ai_service.rb, AiAgentEditor.vue).
5	DEP — Dependencies	FE	8.0	§1 dependency table with owner/status/blocking; the one blocking dep (upstream) is flagged and Chunks 1–8 declared independent of it. Design refs present (Figma pending, prototype canonical).
6	NFS — Non-Functional	FE	8.0	Bundle ≤15 KB gzip, INP <200 ms for Accept, WCAG AA with ARIA/keyboard/prefers-reduced-motion (§3.E). Browser matrix = "repo status quo" (slightly soft).
7	TPS — Test Plan	FE	8.5	§4.C command table with what-it-proves; per-chunk acceptance in §4.D; E2E happy-path spec; seeded-2-flaw config-audit staging scenario.
8	DMS — Data Model & Schema	BE	8.0	No new tables by design (ADR-4), justified; erDiagram of the touched existing slice; DDL N/A with the parameters jsonb migration cited (verified real). Appropriately complete for a stateless feature.
9	ACV — API Contract & Versioning	BE	8.5	§2.4 full request/response JSON, status-code matrix, error shape, upstream contract quoted verbatim, idempotency ("safe to repeat — writes nothing"), additive v2. Caveat: upstream contract is documented-not-deployed (REV-3).
10	DIC — Data Integrity & Consistency	BE	8.5	§2.D matrix — refine no-write spec-asserted (parameters/updated_at unchanged); apply reuses the existing txn + sync-rollback (update_ai_agent.rb:59–67, verified); §2.E collision map.
11	FMC — Failure Mode Coverage	Merged	9.0	§3.A merged catalog with a code-shape-consistency column, §3.A.1 branch catalog, §3.B BE + §3.C FE error catalogs, dedicated failure-path sequence diagrams. FE error handler matches BE {error:{messages:[]}} (verified useGenerateAgent.ts:79).
12	CSS — Concurrency & Scaling	BE	7.5	Human-paced volume argued; 60 s worker-hold consequence named with a rollout watch; single-flight per panel; rate limiting deferred to pre-GA (OQ-7) — the one soft spot, honestly flagged.
13	SAS — Security & Authorization	BE	8.5	§3 threat model (5 threats) + mitigations; input validation per field; no-v-html XSS rule; org-scoped tenancy; Role×Endpoint matrix; secrets reuse.
14	ROL — Rollout & Rollback	Merged	8.5	Deploy order BE-first with rationale; single flag gates both layers; §4.A compat matrix (all safe/degraded-safe); §4.E ordered rollback recipe incl. the Chunk-1 sync-regression canary; stop conditions.
15	OBS — Observability	Merged	8.5	§3 maps PRD §13 events to FE Mixpanel + BE structured logs (reconciled to what actually exists — no BE event bus); alerts, dashboard, "3 am" runbook, PII-scrub rule. Both layers covered.
16	SBC — Service Boundary & Coupling	BE	8.5	Topology + per-service responsibility diagrams; synchronous thin-proxy posture matching the drafter; §2.F.1 responsibility-boundary matrix; no inbound webhooks (async mismatch deliberately avoided).
17	CPA — Pattern Alignment	Merged	8.0	§2.0 patterns-to-follow (both layers, "Deviation? none"), existing-code anchors, Design↔Code map; snake_case passthrough convention verified. Docked to 8.0: an agent following the Reading Guide by line lands off (REV-1) and two paths are wrong (REV-2).
18	CDG — Compliance & Data Governance	BE	7.5	Triggered (PII in transit — tenant-pasted customer content). §3.D table: nothing stored, TLS-in-transit, content-scrub logging rule, UU-PDP processor basis unchanged. Open: upstream retention policy (OQ-1f).

Resource & Cost Advisory (non-blocking)

• §4.F is honest and correct: no new pods/workers/infra; +2 lightweight SELECTs per turn; zero storage growth (stateless); cost center is upstream LLM tokens (Data/ML-owned), bounded on our side by the 10-turn history cap. No advisory concern affects the score.

---

Decision Closure Assessment

Decision Index

#	Decision	Status	Critical Gaps
1	Upstream applies patches (surgical-patch guarantee); BE thin passthrough	Resolved	none — consequence (invented ref caught at Save) is spelled out
2	Apply reuses PATCH /v2/ai_agents/:id (no new write path)	Resolved	none
3	Extract SkillPackBuilder with pluggable vector resolver	Resolved	seam is concrete; risk mitigated by Chunk-1 byte-identical regression spec
4	Stateless BE; FE owns thread	Resolved	none
5	Synchronous proxy, 60 s timeout, no cache, no retry	Resolved	worker-hold consequence acknowledged
6	Response options[] (1..3); legacy → 422	Resolved	none — BE wraps upstream's single proposal
7	FE diffs mapped capability_packs, not raw RFC-6902	Resolved	differ specified; field-map deferred (REV-6, an interface detail not a decision gap)
8	Never auto-apply	Resolved	PRD Non-Goal 1
9	No caching	Resolved	folded into Decision 5
10	Legacy-agent guard → 422 not 404	Resolved	rationale given

Aggregate: 10 of 10 decisions Resolved, 0 Partial, 0 Dangling. The open items in §5 are dependency verifications and deferred product decisions (KB policy, rate limiting, audit-prompt tuning), not unresolved technical decisions — correctly kept out of the ADR set.

Because every decision is Resolved, per-decision deep-dives are abbreviated (all ≥ 7.0). The only one worth a challenge note: Decision 3 (builder extraction) is the single change to shared Phase-1 code and thus the highest-blast-radius task; the RFC lands it alone as Chunk 1 behind a byte-identical request-body regression spec on the real sync_to_ai_service_spec.rb (verified to exist) — this is the correct de-risking and is directly agent-verifiable.

---

Cross-Layer Contract Verification

Endpoint	Backend Response Schema	Frontend Expected Schema	Match?	Gaps
POST /:id/refine	data.reply, data.options[].{id,label,description,recommended,patches,updated_capability_pack,warnings}, data.warnings (snake_case)	useRefineAgent consumes snake_case directly; maps recommended→isRecommended, derives changes/pendingData from updated_capability_pack	Yes	Derivation-by-design (ADR-7), not a mismatch. capability_pack shape identical to GET /:id + generate responses the FE already parses (parseDetailResponse).
PATCH /:id	existing update_ai_agent_response	existing useSaveAgent.buildPayload	Yes	Unchanged contract (verified: bot-automation-agents.update PATCH at :232–247).
upstream refine-skill-pack	{status, reply, patches[], updated_skill_pack, warnings[]} — single proposal (skill_pack shape)	BE SkillPackMapper parses the same skill_pack shape it already handles from draft-skill-pack; use case wraps into options:[one]	Yes (on paper)	The BE↔upstream contract is documented-not-deployed (REV-3) + fast-follow asks in OQ-1b/c/e.

Checks performed: casing ✓ (snake_case passthrough, repo convention verified) · nullability ✓ (empty options:[] path defined) · error shape ✓ (FE response._data.error.messages[0] matches BE Grape convention) · pagination n/a (single-turn RPC) · auth ✓ (reuses existing Http client creds).

Mismatches found: 0 — no ROL cap triggered.

---

Cross-Layer Rollout Compatibility Matrix

Scenario	Frontend	Backend	Works?	Notes
Pre-deploy (baseline)	Old	Old	Yes	current state
Backend first	Old	New	Yes	new route unused; flag OFF
Frontend first	New	Old	Partial (degraded-safe)	tab hidden unless flag payload present; a raced call 404s into the error turn — avoided by BE-first order
Both deployed (target)	New	New	Yes	flag ON = target
Backend rollback	New	Old	Partial (degraded-safe)	refine sends fail into retryable error turn; editor/save unaffected; flip flag OFF
Frontend rollback	Old	New	Yes	endpoint idle

Deploy order: Backend first (explicit, with rationale). Incompatible scenarios: 0 hard "No" — the two Partials are degraded-safe and covered by the single-flag + BE-first plan. ROL uncapped.

---

End-to-End Data Flow

Flow: Refine turn → accept → save (traceable end-to-end from §2.1/§2.2/§2.H)

Tenant types message in Refine tab
  → FE: RefinePanel → useRefineAgent.refine() (truncate chat_history to last 10)
  → API: POST /v2/ai_agents/:id/refine
  → BE: Grape route (Ownership → set_role → flag gate) → UseCases::RefineAiAgent
        → FindBy(id, org_id) → engine_version==2 guard
        → Mappers::SkillPackBuilder (READ-ONLY vector resolver — no vector DB created)
        → Repositories::Refine (gather available_tools) → AiService::AiAgent#refine_skill_pack
  → Upstream: refine-skill-pack (LLM diagnose + surgical-patch apply) → {reply, patches, updated_skill_pack, warnings}
  → BE: SkillPackMapper per option → 200 {reply, options[], warnings}  [NOTHING PERSISTED]
  → FE: differ builds ProposedChange[] → thread renders reply + option cards
  → Accept: applyPendingData → form model + aiChangedFields highlight + activeTab switch (NO HTTP)
  → Save: PATCH /v2/ai_agents/:id → txn { Update + PaperTrail version + SyncToAiService(:update) → PUT /ai-agent }
  → Side effects: BE logs (refine requested/succeeded); FE Mixpanel (refine_requested/succeeded/accepted/applied)

Gaps in flow: the full path is documented in one place (§2.H) and matches the sequence diagrams — no piecing-together required. The one under-specified hop is the updated_capability_pack → real AgentDetailConfig form-model write inside applyPendingData (REV-6): the field/label mapping is named-but-not-tabulated. Multi-turn context carry-through across turns is unverified (REV-4).

---

Agentic Readiness Deep-Dive

Vague Word Audit

Spec sections are unusually concrete (contracts, counts, timeouts, exact commands). No blocking vagueness. Minor: "tens of RPM org-wide" (§3) is an estimate not a budget — acceptable for a flag-gated feature; "Pixel tokens verified at design QA once frames land" (§3.E) defers contrast confirmation to design QA — acceptable. Total blocking vague words: 0.

Dangling Alternatives

0 in the spec body — every "Option A vs B(/C)" resolves to a stated Decision.

Task Decomposition Assessment

Chunk	Acceptance Criteria	Assessment
1 BE builder extraction	byte-identical request body pre/post; read-only resolver asserts no create_vector_db	verifiable
2 BE flag	predicate true only when row enabled; absent→false	verifiable
3 BE client method	POST to exact path + 60 s timeouts (mock)	verifiable
4 BE Repositories::Refine	body matches §2.4 upstream schema for fixture	verifiable
5 BE use case + route	full status matrix; DB row unchanged; 5xx→422	verifiable
6 FE service + composable	history cap slices to 10; differ add/update/remove rows; abort on dispose	verifiable
7 FE rail + panel	5 UI states; Accept mutates form/highlights/tab, no HTTP; gate hides tab	verifiable
8 FE analytics + i18n	events fire with count-only props	verifiable
9 both E2E + staging	E2E green; staging refine ≤10 s p95; save applies staged pack; PaperTrail +1	blocked on real upstream (REV-3)

Chunks 1–8 have crisp, runnable acceptance criteria. Chunk 9 is the only externally-gated one.

---

Strengths

• Verified grounding, not claimed grounding. I checked ~60 citations against the real chatbot/chatbot-fe/qontak-designer trees: update_ai_agent.rb full-merge + txn + CapabilityRefPresence macros, sync_to_ai_service.rb builders + resolve_capability_vector_store raising VectorStoreSyncError, skill_pack_mapper.rb COMPLETION_TYPE_MAP + Entities::AiAgent(engine_version: 2), the drafter's 60 s timeouts, has_paper_trail, the parameters jsonb migration, zero pre-existing refine code, and the prototype's ProposedChange/PendingData/acceptRefineOption + verbatim chip click-payloads — all real.
• Decision closure is textbook (10/10 Resolved, §2 ADR blocks) and the reconciliation table (§1) turns external-doc contradictions into repo-wins-decisions with the correct call each time (PaperTrail-not-ai_agent_histories, page-not-modal, rail-already-exists, as-built-does-not-strip-refs).
• Failure and rollout rigor (§3.A/§3.A.1/§3.B/§3.C + §4.A/§4.E): cross-layer error-shape consistency, a branch catalog, a flag-flip rollback with no deploy, and a Chunk-1 sync-regression canary. All 11 Mermaid diagrams parse.

Biggest Gaps

• REV-3 (major, external): the feature is a proxy in front of an unverified-deployed upstream (§5 OQ-1a, §7). Nothing an agent writes can close this; it caps completion at Chunk 8 until Data/ML confirms deployment.
• REV-4 (major): OQ-11 leaves the multi-turn context mechanism unconfirmed — REFINE-S03/AC-1 ("response reflects earlier context") is built as a flat last-10 re-send whose sufficiency the RFC itself doubts.
• REV-1 (major, mechanical): stale line numbers across the Reading Guide / Source Verification / Design↔Code tables, worst in the 5,529-line AiAgentEditor.vue (~+85). Symbols correct, so recoverable — but the RFC presents these numbers as authoritative and they will misdirect a line-trusting agent.

Priority Actions

1. §5 OQ-1a (REV-3) — get Data/ML to confirm refine-skill-pack is deployed and exposed at /qontak-ai-noncore-mrag/api/ai-agent/refine-skill-pack in staging/prod. This is the only thing between "build Chunks 1–8" and "flip §7 to yes." Nothing else blocks starting.
2. §5 OQ-11 (REV-4) — confirm with Data/ML how chat_history must be structured/bounded so a follow-up turn actually inherits prior context; if a flat last-10 re-send is insufficient, REFINE-S03 needs a revised request shape before Chunk 9.
3. §2.0 + §2.A (REV-1, REV-2, REV-6) — re-ground the line numbers (or switch to symbol-anchored citations and note that AiAgentEditor.vue/prototype drift), fix the two BE helper/middleware paths (app/api/frontend_service/{helpers,middlewares}/), and add an explicit updated_capability_pack→AgentDetailConfig field/label map to Detail 2.A.
4. Detail 1.A + §3.A.1 (REV-7) — update the two "REFINE-S01/AC-4 needs PRD correction" cells to "corrected in PRD v1.5.1" so the RFC stops flagging an already-fixed drift.

---

Backend Contract Addendum

Endpoint Contract Details

Endpoint	Method/Path	AuthZ	Request Contract	Response Contract	Error Contract	Idempotency/Versioning	Status
Refine	POST /v2/ai_agents/:id/refine	Ownership + set_role(owner/supervisor/admin) + flag ai_agent_refine	user_message 1..4000 (req), chat_history[] ≤10 (role enum + content 1..4000), trace opaque ≤8 KB (optional, omitted v1)	data.reply (str), data.options[] 0..3 (id,label,description,recommended,patches,updated_capability_pack,warnings), data.warnings[]	200/400/403/404/422 (not_autonomous_agent on legacy); shape {error:{messages:[]}}	Safe-repeat (no write); v2 additive	Complete
Apply (reused)	PATCH /v2/ai_agents/:id	existing	existing full-merge profile/capabilities/routing	existing update_ai_agent_response	400 (CapabilityRefPresence), 422 (sync rollback)	last-writer-wins full merge	Complete (unchanged)

Database Changes Details

Change	Table/Entity	DDL / Shape Diff	Data Migration	Rollback	Compatibility	Status
None (ADR-4)	—	zero migrations; reads ai_agents.parameters (jsonb, existing) + ai_agent_tools; one system_preferences seed row	none	flag flip / PaperTrail restore	fully additive	Complete

---

Implementation Readiness Checklist

Unblocked (agent can proceed)

• PRD → RFC traceability complete
• All technical decisions resolved with alternatives rejected
• Failure modes handled per interaction with an error catalog (§3.A–C)
• Configuration contract documented (§4.B: flag, path constant, timeouts, history cap with defaults)
• Pattern alignment verified (§2.0) — modulo REV-1/REV-2 line/path drift
• Rollout plan with flag + rollback (§4.A/§4.E)
• Observability metrics + alerts (§3)
• Task decomposition with per-chunk acceptance (§4.D)
• FE interfaces / prop types specified (§2.A) — modulo REV-6 field-map
• All UI states defined (§2.C) · a11y specified (§3.E) · perf budget quantified (§3)
• Cross-layer contract verified (§2.G) · deploy order specified (BE-first) · rollout matrix has no hard "No" · E2E flow documented · single-flag coordination defined
• No new schema; API contracts with full schemas + error taxonomy; txn/idempotency per write path; collision map; security/tenancy; migration/rollback; service boundary; compliance (PII-in-transit) handled

Blocked (must fix first)

• REV-3 / OQ-1a — upstream refine-skill-pack deployment + gateway exposure unverified (blocks Chunk 9 + end-to-end acceptance only)
• REV-4 / OQ-11 — multi-turn chat_history context semantics unconfirmed (risks REFINE-S03 rework)

Verdict: Ready to implement Chunks 1–8 now; 2 external/behavioral items gate Chunk 9 and full acceptance.

---

Task Manifest

The RFC specifies a 9-chunk plan (§4.D) that is complete and verifiable; reproduced with review annotations. No re-derivation needed.

Order	Chunk	Files to Create/Modify	Acceptance Criteria	Dependencies
1	BE SkillPackBuilder extraction	+use_cases/mappers/skill_pack_builder.rb (+spec); ~repositories/sync_to_ai_service.rb; ~repositories/sync_to_ai_service_spec.rb	existing sync specs green; byte-identical request-body snapshot; read-only resolver asserts no create_vector_db	None
2	BE flag predicate	seed system_preferences rollout/ai_agent_refine; predicate (pattern system_preference.rb:41–51)	predicate true only when enabled; absent→false	None
3	BE upstream client	~lib/ai_service/ai_agent.rb add refine_skill_pack	POST to exact path + 60 s timeouts (mock)	None
4	BE Repositories::Refine	+repositories/refine.rb	body matches §2.4 upstream schema for fixture	1,3
5	BE use case + route + response model	+use_cases/refine_ai_agent.rb, +models/refine_response.rb; ~ai_agents_controller.rb	full status matrix; DB row unchanged; 5xx→422	2,4
6	FE service + composable	~endpoint.ts, ~bot-automation-agents.ts; +useRefineAgent.ts (+differ)	history cap 10; differ rows correct; abort on dispose	5 (contract)
7	FE rail + panel	~AiAgentEditor.vue; +RefinePanel.vue, +RefineOptionCard.vue	5 states; Accept mutates form/highlights/tab, no HTTP; gate hides tab	6
8	FE analytics + i18n	wire trackEvent; locale keys	events fire with count-only props	7
9	E2E + staging	Playwright spec; staging run	E2E green; ≤10 s p95; save applies staged pack; PaperTrail +1	1–8 + real upstream (blocked, REV-3)

---

Dangling Decisions Log

#	Decision	Location	Owner	Deadline
—	None — all 10 ADR decisions Resolved	§2	—	—

---

Open Questions

Still-open material findings, cross-referenced to the RFC's own §5 where they already exist. Promote by REV-n.

#	Question	Category	Severity
REV-3 / OQ-1a	Is upstream refine-skill-pack actually deployed + exposed via the noncore-mrag gateway path?	DEP / ACV	Blocking (for Chunk 9 + acceptance)
REV-4 / OQ-11	How must chat_history be structured/bounded so follow-up turns carry prior context — is a flat last-10 re-send sufficient for REFINE-S03/AC-1?	ACV / PRT	Important
REV-5 / OQ-4	On Apply, allow KB-affecting patches (vector re-resolve) or reject them? Which patches can refine even emit?	DIC / SCB	Important (before Closed Beta)
REV-1	Re-ground or symbol-anchor the drifted line numbers (esp. AiAgentEditor.vue ~+85, prototype ~+18)	CPA	Important
REV-6	Tabulate the updated_capability_pack→AgentDetailConfig field/label map in §2.A	CNT	Important
REV-2	Correct the two BE helper/middleware paths (FE-service scope, not v2/ai_agent/)	CPA	Nice-to-have
REV-7	Update the two "AC-4 needs PRD correction" cells (PRD already corrected)	PRT	Nice-to-have
OQ-1g	Confirm complaint-free config-audit prompts are tuned/tested (REFINE-S04 reliability)	FMC	Important (before Closed Beta)
OQ-7	Add per-org refine rate limiting before GA	CSS	Nice-to-have (before GA)

---

Evidence Notes

• Grounding pass (highest impact on confidence): three parallel repo audits confirmed ~60 symbol/pattern/contract claims across chatbot, chatbot-fe, qontak-designer. Result: symbols/contracts all real → High confidence, top-band scores justified; line-number drift → REV-1, docked CPA to 8.0 rather than 9.0.
• §2.4 APIs + §2.G contract verification — full BE↔FE and BE↔upstream schemas present and mutually consistent; drove ACV/DIC/FMC high; the only weakness is upstream deployment (REV-3), a dependency not a contract defect.
• §5 Open Questions — unusually candid (13 items, several marked Resolved with dates). OQ-11 and OQ-4 are the two that carry real build risk; the rest are dependency verifications or deferred product calls. This candor is why the RFC scores as Agentic-Ready despite declaring itself §7 "not ready" — the not-ready is an external gate, correctly separated from spec completeness.
• Mermaid — 11/11 blocks parse under @mermaid-js/mermaid-cli; confirms the RFC's own 2026-07-05 comment-log claim.
• PRD (v1.5.1) — as-built corrections (PaperTrail, surgical-patch, rail-exists) already landed; RFC and PRD agree except the cosmetic REV-7 drift.

---

Review History

Cycle	Date	Reviewed RFC revision (last_updated / commit)	Score	Verdict	Findings open → fixed	Notes
R1	2026-07-08	2026-07-07 / 15aa71d	8.5	PROCEED with notes	7 open (3 major, 4 minor), 0 fixed	First cycle. Grounded against real BE/FE/designer repos — citations all real, line numbers drifted. Only true gate is external upstream deployment (OQ-1a).