Separating AI-Generated Proposals from Human-Reviewable Docs in AAIC

AliExpress's AAIC (Agentic AI Community) is an AI coding tool built for large-scale, high-frequency delivery in complex organizations. It enhances reliability through domain-specific knowledge bases (G1–G5), a standardized four-phase delivery process ( /aaic:explore, /aaic:propose, /aaic:apply, /aaic:test), and reusable team assets via Skills.

Problem: One Proposal, Two Audiences

The propose-output.md produced in the propose phase targets AI code generation, containing exhaustive implementation details — code snippets, internal logic, functional layers (L1–L5), file anchors. However, technical proposal reviews require cross-functional consensus among product, frontend, QA, and partner teams. The AI-oriented document overloads human reviewers with implementation noise, causing two issues:

Comprehension overhead : Reviewers struggle to extract "what changed" amid code fragments.

Collaboration friction : Key decision points (experiment configs, multi-language settings, protocol changes, parameter shifts, risk flags) are buried, slowing cross-functional alignment.

In short: AI proposals are implementation-centric ; reviews need reader-centric documents.

Solution: Document Responsibility Separation + Reader-Perspective Modeling

Instead of compressing the detailed proposal (which would starve code generation), the team separates concerns:

Detailed Technical Proposal ( propose-output.md): For AI/developers, full implementation detail, single source of engineering truth.

Reviewable Technical Proposal : For collaborators, only core elements — protocol changes, interface impacts, risks, copy, experiment configs.

Two key designs enable this:

Templated extraction : A Skill pulls key review items from the detailed proposal and PRD, restructuring them into a standardized, domain-defined template (e.g., .repos/*-skills/reference/propose_reviewable_template.md). The template enforces a fixed chapter skeleton — Overview, Solution Design, Risk Assessment, Configurations, Project Plan — with zero implementation-detail chapters.

Role adaptation : Content is phrased in business terminology per reviewer role (e.g., interface changes described for partner devs, not code-level diffs).

Reader Perspectives for Transaction Domain

The team abstracted five perspectives and their focus areas:

Product/Operations : Medusa multi-language config, project cadence, feature completeness

QA : Main logic, risk points, feature flags

Partner domains : Input/output parameter changes

App developers : Flows, domain changes, protocol changes, collaboration touchpoints

This perspective list drives template chapters and sub-agent assignments.

Architecture: Four-Layer Generation Pipeline

4.1 Business Template: Document Skeleton

The reviewable proposal is generated at propose-end by a sub-agent using three inputs: current propose-output, PRD, and the domain's custom template. The AE transaction template skeleton:

# Overview
  Background / References / Goals (business & technical)
# Solution Design
  Feature list / Core flows / View protocol design / Interface protocol design / Business logic changes
# Risk Assessment
  Technical complexity risk / Financial risk
# Configurations
  Switch / Diamond / Medusa / Experiment
# Project Plan
  Integration test, QA, release, rollout dates

Each chapter maps to at least one reader perspective. The template is a hard constraint: chapter structure is immutable, giving reviewers stable mental models.

4.2 Perspective Specs: Right Person Writes Each Chapter

Five reference files under the Skill directory define role, chapter specs, constraints, and self-check lists: ref-perspective-product.md — Product/Ops → produces Background, business goals, Medusa/experiment, project plan ref-perspective-testing.md — QA → produces Feature list, technical complexity risk, financial risk ref-perspective-frontend.md — Frontend → produces View protocol design ref-perspective-partner-dev.md — Partner dev → produces Interface protocol design ref-perspective-app-dev.md — App dev → produces Technical goals, core flows, key design, business logic changes, Switch/Diamond config

Why not one giant prompt? A monolithic prompt degrades to "average" output — every chapter gets a little, none gets depth. Perspective-specialized sub-agents each adopt a single reader's stance, producing content that matches that reviewer's expectations.

4.3 Orchestrator Skill: Pure Coordination

The core Skill ( ae-trade-propose-guide-reviewable-tech-solution) is a pure orchestrator — it only: agrees input contract → reads docs → parallel dispatches → integrates & audits. It explicitly does not write chapters, re-do technical research (the propose-output is the sole engineering truth), or define chapter formats (delegated to perspective references).

Execution flow:

Step 1: Input contract . propose_output required; PRD and template auto-discovered (template via .repos/*-skills/reference/propose_reviewable_template.md; PRD extracted from propose-output Yuque links or user-confirmed).

Step 2: Read docs . Parse template skeleton (titles + semantics), fully read PRD(s) and propose-output, validate completeness.

Step 3: Parallel dispatch . For each sub-agent, build a three-part prompt (full perspective spec + template skeleton + raw PRD/propose-output corpus), then launch all five sub-agents simultaneously in one message — no inter-agent communication.

Step 4: Integrate & audit . Merge by template order; cross-chapter deduplication & consistency checks (feature list ↔ key design ↔ logic changes must align; frontend-referenced interfaces must exist in interface protocol); source audit — every claim must trace to PRD/ propose-output, missing info marked 【待确认】 and collected into risk table. A final checklist enforces two "hygiene" rules: no code anchors ( #L123), line numbers, or L4/L5 labels; no iterative process descriptions. Any violation triggers re-dispatch.

An information-source guide table tells each chapter its primary and supplementary sources (e.g., Feature List ← propose-output L3/L4 tables + PRD; Technical Complexity Risk ← propose-output TBDs/dependencies + PRD exception scenarios).

4.4 Platform Integration: Default Behavior

A hook at the end of the AAIC propose command auto-triggers the Reviewable Proposal Agent. If the domain has a template, every propose run emits a review draft — zero extra steps for developers.

Results

Side-by-side comparison shows the AI proposal forces collaborators to parse code and L1–L5 layers, while the reviewable proposal lets frontend focus on protocol changes, QA on risks/flags, etc. Adoption metrics (demand coverage, generation rates) are tracked on a dashboard.

Key Takeaways

In the AI coding era, documents must layer by reader, not by phase. propose-output serves AI; reviewable proposal serves humans — their information-density needs are fundamentally different.

Orchestrator/content separation is a viable long-document agent architecture. Main Skill handles orchestration (input contract, parallel scheduling, consistency audit, source audit); perspective specs handle content; template handles structure. Decoupled, new domains only need a template + optional perspective tweaks — orchestration logic fully reused.

"No hallucination + source audit" is the reviewable proposal's lifeline. A fabricated interface or config in a review doc builds consensus on falsehoods — worse than no doc. Four guardrails: single truth source ( propose-output), per-chapter source guide, integration-time audit, 【待确认】 fallback.

Capabilities must live in the flow. Hooking into propose and convention-based template paths turn "one more step" into "happens by default" — the decisive factor for adoption.

The capability runs in AE transaction domain. Teams using AAIC who struggle with "AI proposals unreviewable" can reuse the perspective specs and orchestrator design directly.