Overview: The Interactive Review Loop
When you allow an AI coding assistant (in Cursor, Claude Code, Windsurf, or Google Antigravity) to propose App Store Connect modifications, you never want the model to push mutations blindly to Apple. However, simple binary approval ("Yes/No") creates friction: if an agent drafts release notes with a minor phrasing defect or stages a price tier that is slightly off, outright rejection forces you to re-prompt the agent from scratch with manually copied context.
FlightDeck bridges this gap with the Request Changes Feedback Loop. Built natively into FlightDeck Desktop’s Approval Center, this workflow allows you to review staged proposals, type natural-language corrections, and return structured human guidance directly across the local Model Context Protocol (MCP) connection.
┌─────────────────────────────────────────────────────────────────────────────┐
│ THE 'REQUEST CHANGES' REVISION WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ [AI ASSISTANT] │
│ │ Proposes release notes, metadata, or version updates │
│ ▼ │
│ flightdeck_change_set_stage (status: pendingHumanReview) │
│ │ (Zero HTTP calls to Apple; held in local memory & disk) │
│ ▼ │
│ [FLIGHTDECK DESKTOP APPROVAL CENTER] │
│ │ Human reviews visual cards & diffs │
│ │ Click: [Request Changes] -> Types: "Remove mention of Android" │
│ ▼ │
│ Status transitions to CHANGES_REQUESTED (Terminal State) │
│ │ │
│ flightdeck_change_set_status (Poll or Long-Poll with waitTimeoutSeconds) │
│ │ Returns humanFeedback & perOperationFeedback │
│ ▼ │
│ [AI ASSISTANT INGESTS GUIDANCE] │
│ │ Revises prompt context & generates corrected payload │
│ ▼ │
│ flightdeck_change_set_stage (supersedesChangeSetId: "cs_123") │
│ │ Brand-new staged proposal requiring fresh human approval │
│ ▼ │
│ [APPROVAL CENTER] -> Human reviews revised diff -> Click: [Approve] │
└─────────────────────────────────────────────────────────────────────────────┘
This guide explains the architectural state machine behind the Request Changes lifecycle, how feedback is transmitted to your AI assistant, and how to structure prompts so your assistant seamlessly incorporates feedback.
The Request Changes State Machine in FlightDeck
FlightDeck enforces strict security boundaries around all mutation proposals. Understanding the underlying state transitions prevents misunderstandings about what is happening on Apple’s servers versus your local machine.
1. Terminal State Invariant
In FlightDeck’s architecture (packages/asc_safety/lib/src/change_set_status.dart), ChangeSetStatus.changesRequested is an immutable, terminal state:
// Valid lifecycle statuses for a proposed ChangeSet
enum ChangeSetStatus {
pendingHumanReview,
directExecutionEligible,
approved,
changesRequested, // Terminal state
rejected, // Terminal state
expired, // Terminal state
cancelled, // Terminal state
supersededByPolicyChange,
requiresReapproval,
consumed;
bool get isTerminal =>
this == changesRequested ||
this == rejected ||
this == expired ||
this == cancelled ||
this == supersededByPolicyChange ||
this == consumed;
}
Because changesRequested is terminal, an existing staged Change Set cannot be mutated in place. Once you click "Request Changes" in the desktop UI:
- The original staged record is locked permanently.
- The execution secret (
continuationSecret) is invalidated and cannot be used to trigger Apple mutations. - The AI assistant cannot "patch" or "resume" the closed record.
- The assistant must generate and stage a completely new Change Set.
2. Feedback Data Model & Retention
When you submit revision notes in the FlightDeck Desktop Approval Center, your input is captured through requestChangesFromTrustedDesktopHumanAction (change_set_repository.dart):
- Overall Feedback: A high-level explanation of what needs to change across the entire proposal (up to
ChangeSetLimits.maxFeedbackLength, defaulting to 2,000 characters). - Per-Operation Feedback: Granular notes attached to specific operation indices within a batch (e.g. Operation 0 accepted, but Operation 2 rejected due to invalid keywords).
- Per-Operation Dispositions: Review status per item (
acceptable,changesRequested,unreviewed). - Audit Persistence: The change set, its fingerprint, and the complete text of your human feedback are written immediately to the append-only local audit log (
~/Library/Application Support/asc_mcp/audit.jsonl). Feedback survives application restarts.
No Autonomous Rewriting by FlightDeck: FlightDeck itself never rewrites or alters an AI assistant's proposal. The revision loop relies on your AI coding assistant (Cursor, Claude Code, Windsurf) retrieving the structured feedback across MCP, adjusting its own generation prompt context, and submitting a completely new, distinct Change Set for human review.
How AI Assistants Retrieve and Process Feedback
FlightDeck provides two mechanisms for your AI assistant to learn about human review decisions: asynchronous polling and long-polling waiters.
Polling via flightdeck_change_set_status
When an AI assistant stages a proposal via flightdeck_change_set_stage, FlightDeck returns the changeSetId and polling instructions:
{
"changeSetId": "cs_9f83a21b",
"status": "HUMAN_APPROVAL_REQUIRED",
"operationCount": 3,
"expiresAt": "2026-11-04T02:15:00.000Z",
"message": "Change Set staged for human approval. Poll flightdeck_change_set_status until approved or deadline."
}
The AI assistant checks the review disposition by invoking flightdeck_change_set_status. FlightDeck supports a waitTimeoutSeconds parameter (from 0 to 5 seconds). If the proposal is still pending, FlightDeck’s ApprovalStatusWaiter pauses the HTTP response until a human acts or the short timeout elapses, avoiding excessive CPU loops.
When you click "Request Changes" and submit your notes, the subsequent call to flightdeck_change_set_status returns:
{
"changeSetId": "cs_9f83a21b",
"title": "Update Version 1.2.0 Release Notes and Promotional Text",
"status": "CHANGES_REQUESTED",
"humanFeedback": "The release notes mention Android parity features. Apple Guideline 2.3.10 prohibits mentioning other mobile platforms. Strip all references to Android and emphasize the new macOS widgets instead.",
"perOperationFeedback": {
"0": {
"operationId": "appStoreVersionLocalizations_updateInstance",
"reviewDisposition": "changesRequested",
"humanFeedback": "Remove Android mention from whatsNew."
},
"1": {
"operationId": "appStoreVersionLocalizations_updateInstance",
"reviewDisposition": "acceptable"
}
},
"actionRequired": "REPORT_CHANGES_REQUESTED",
"message": "Human reviewer requested changes for this Change Set. Review humanFeedback and do not proceed with execution."
}
The Revision Cycle: Staging with supersedesChangeSetId
Once the AI assistant parses actionRequired: "REPORT_CHANGES_REQUESTED", it understands that:
- It is forbidden from calling
flightdeck_change_set_execute. - It must read
humanFeedbackand update its draft. - It must call
flightdeck_change_set_stagewithsupersedesChangeSetId: "cs_9f83a21b".
By populating supersedesChangeSetId, FlightDeck links the new proposal to the prior revision in the desktop timeline, allowing you to compare the original proposal against the revised draft.
Step-by-Step Walkthrough: Guiding an AI Assistant Through a Revision
Here is the exact conversational flow to establish an effective revision loop with your AI assistant.
Step 1: Initial Instruction Prompt
Give your AI coding assistant an outcome-oriented prompt that instructs it to stage changes and await review:
Prepare the metadata update for version 1.2.0 of our iOS app.
Update the English (U.S.) release notes with the bug fixes from our latest git commits.
Stage the changes in FlightDeck so I can review them in the Desktop Approval Center.
Do not attempt to execute any mutations until I explicitly grant approval.
Step 2: Review in FlightDeck Desktop
- Open FlightDeck Desktop and navigate to the Approval Center tab.
- You will see an active card for the staged change set displaying the exact proposed payload: - Target Application ID - Operation ID (
appStoreVersionLocalizations_updateInstance) - Resource ID - Exact text of the newwhatsNewfield. - If you notice an issue (for example, promotional claims that violate App Store Review Guidelines), click the Request Changes button.
- An inline text area appears. Enter your instructions: > "The third bullet point mentions beta testing. Remove all references to beta software to avoid App Store Guideline 2.2 rejections. Replace it with 'General performance and stability improvements'."
- Click Submit Feedback.
Step 3: Agent Response & Follow-Up
When the assistant checks status, it receives your exact instructions. It will reply in your editor:
"You requested changes on the version 1.2.0 metadata update: 'Remove all references to beta software to avoid App Store Guideline 2.2 rejections.' I have updated the release notes and staged a revised Change Set (
cs_a1b2c3d4) superseding the original. Please review the updated card in FlightDeck Desktop Approval Center."
Step 4: Final Approval and Execution
- Return to FlightDeck Desktop. The old card is marked
Changes Requested(archived), and a fresh card forcs_a1b2c3d4is visible. - Verify that the beta reference has been replaced.
- Click Approve.
- The assistant detects approval and completes execution via
flightdeck_change_set_execute.
Operational Comparison: Action Dispositions in FlightDeck
| Action in Desktop UI | Resulting Status | Is Terminal? | Effect on Staged Token | Action Required by Agent |
|---|---|---|---|---|
| Approve | approved |
No | Validated for execution | Executes via flightdeck_change_set_execute |
| Request Changes | changesRequested |
Yes | Permanently revoked | Ingests feedback, revises, stages new Change Set |
| Reject | rejected |
Yes | Permanently revoked | Halts workflow; reports rejection reason to user |
| Discard / Cancel | cancelled |
Yes | Permanently revoked | Clears queue; no further actions taken |
| TTL Timeout (15m) | expired |
Yes | Expired | Must re-verify live state and re-stage |
Best Practices for Prompting and Reviewing
Be specific in your UI feedback: FlightDeck transmits your exact desktop text to the AI model's context window. Writing concise, actionable feedback (e.g. "Change keyword 'crypto' to 'budgeting'") produces immediate, accurate revisions on the first retry.
Zero Changes Reach Apple Until Final Approval: Requesting changes is completely local. No HTTP requests are sent to api.appstoreconnect.apple.com during the revision loop. You can request changes five times in a row without risking account rate limits or creating broken drafts in App Store Connect.
Watch for Context Drift: If you request multiple revisions, remind your AI assistant to preserve unrelated metadata fields that were already correct in earlier steps.
Troubleshooting the Feedback Loop
The AI Assistant Stops Polling After Changes Are Requested
- Cause: Some coding clients stop polling when they receive a status other than
HUMAN_APPROVAL_REQUIREDorAPPROVED. - Remedy: In your editor chat, prompt the assistant: "I have requested changes in FlightDeck Desktop. Check the change set status, read my feedback, and stage an updated proposal."
"ChangeSetTransitionException: Cannot transition from changesRequested"
- Cause: An agent or script attempted to approve, execute, or re-stage against a change set ID that has already been transitioned to
changesRequested. - Remedy: Ensure the assistant creates a new change set with a fresh
changeSetIdinstead of re-submitting the existing ID.
Staged Proposal Shows "EXPIRED" Before You Review
- Cause: FlightDeck proposals carry a default time-to-live (TTL) of 15 minutes to prevent stale mutations from executing against altered remote state.
- Remedy: If a proposal expires, ask your assistant: "Re-check the current App Store Connect status and stage a fresh proposal."
Related Documentation & Authoritative References
- App Store Connect API Staging & Approvals — FlightDeck's core staging and approval policies.
- Connecting Cursor to App Store Connect MCP — Setting up the local MCP server and Approval Center.
- App Store Review Guidelines: Metadata Completeness (Guideline 2.3) — Official Apple guidelines on storefront copy.
- App Store Connect API: Versions & Localizations — Official documentation for App Store metadata resources.