Decision Flow: AI-Assisted Development Lifecycle

This is the official lifecycle for AI-assisted development in ConversionIQ.

It enforces documentation and architectural alignment before implementation to preserve enterprise quality and reduce rework.

Required order of operations

User request
    │
    ▼
1. Neo — Review, document, spec
    │  • Reads relevant docs and current implementation
    │  • Updates or creates docs if needed
    │  • Produces implementation spec / tasks for Coder
    │
    ▼
2. Coder — Implement
    │  • Implements the spec precisely
    │  • Raises blockers or spec gaps before guessing
    │  • Produces minimal, scoped code changes
    │
    ▼
3. QA — Validate
    │  • Verifies implementation matches docs + spec + UX expectations
    │  • Produces issue report or approval
    │
    ▼
4. Refactor (optional)
       • Only after correctness is verified
       • Must not change behavior unless explicitly approved

Step details

1. Neo — Review, document, spec

Read the relevant route/domain docs and current implementation.
Update or create docs in ciq-mvp2-docs/docs/** if the change affects documented behavior.
When the change affects contracts beyond the page layer, update the relevant canonical docs in docs/api/**, docs/prompts/**, docs/workflows/**, docs/ops/**, or docs/rebuild/**.
Produce a clear, actionable spec for Coder: what to build, where, and how it should align with docs.
Identify edge cases, tradeoffs, and delivery risks before implementation begins.
Mark unknowns as TBD and surface them as explicit open questions.

2. Coder — Implement

Receive the spec from Neo.
Implement in ciq-mvp2-app/** following project conventions, stack, and component patterns.
Do not redesign or reinterpret the spec.
If the spec is ambiguous or conflicts with the codebase, stop and raise it — do not guess.
Fix lints introduced by the implementation.

3. QA — Validate

Compare the implementation against the docs, spec, and current UI baseline.
Verify all flows, states, edge cases, and acceptance criteria.
Produce a structured issue report for any mismatches.
Provide explicit approval when everything is correct.

4. Refactor (optional)

Only after QA approval.
Refactors must not change behavior unless explicitly approved.

When to involve each agent

Trigger	Agent
A route is added/removed/renamed, or route behavior changes	Neo
UI/UX changes affect layout, states, permissions, cross-linking, or enterprise constraints	Neo
A domain rule/contract must be clarified (API, data model, events, validation)	Neo
Major architectural tradeoff or high-level system decision	Father (then Neo for detailed spec)
There is an approved spec and the task is ready for implementation	Coder
Implementation is complete and needs verification	QA
Suspected contract drift (docs vs implementation mismatch)	QA
Creating demo data, seed data, UX copy, system prompts, or documentation inputs	Helper
No explicit agent role named in the user prompt	Helper (default)

Operational rules

No implementation-first: if docs are missing or wrong, fix docs first.
Implementation-aware: when shipped UI has advanced beyond historical mocks, use the current implementation as the baseline unless the task explicitly says to restore or follow Figma.
TBD is allowed only when the uncertainty is explicit and does not misrepresent behavior.
Human approval is required for any change that materially affects security posture, data isolation, or compliance expectations.
Figma is optional reference material unless the task explicitly requires it or the user asks for a Figma-driven change.

Request workflow rule (always applied)

Every user request follows this pattern:

Review the request — understand what is wanted and what is in scope.
Documentation — decide if the change requires doc updates. If yes, update docs first.
Implementation — if code changes are needed, delegate to Coder with a clear spec.
Unclear requests — if ambiguous, ask the user before proceeding.

Source: .cursor/rules/request-workflow-review-docs-implement.mdc