A Change Proposal is a persistent, reviewable suggestion to create, update, or connect an entity — surfaced by AI analysis of documents, journeys, meetings, or code, or created manually by a team member. Change Proposals are Catalio’s mechanism for keeping humans in control of what enters the requirements catalog while enabling AI to do the discovery heavy lifting.
The Problem Change Proposals Solve
AI discovery is powerful but imperfect. When Catalio analyzes an uploaded document, processes a meeting transcript, or observes a Journey, it generates many potential requirements signals — some accurate, some redundant, some incorrect.
Rather than automatically creating requirements from AI analysis (which would pollute the catalog with noise), Catalio creates Change Proposals. These proposals surface AI discoveries for human review. Team members accept what is accurate, modify what is close, and dismiss what is wrong.
This pattern is sometimes called “human-in-the-loop AI” — the AI does the initial labor-intensive extraction, humans provide judgment and domain knowledge.
Proposal Action Types
A Change Proposal can propose one of three action types:
| Action | What It Does |
|---|---|
| create | Propose creating a new entity (e.g., a new Requirement) |
| update | Propose changes to an existing entity (before/after field snapshots) |
| connect | Propose linking an existing entity to the Initiative scope |
Proposal Sources
Change Proposals have a source field indicating where the proposal came from:
| Source | Meaning |
|---|---|
| ai_discovery | AI-discovered from context analysis or conversation |
| document_extraction | Extracted from an uploaded document or artifact |
| meeting_extraction | Extracted from a meeting transcript (conservative confidence) |
| manual | Manually created by a team member |
| initiative_analysis | Generated from cross-Initiative analysis |
| artifact_extraction | Extracted from an uploaded artifact via NLP/entity recognition |
| code_analysis | Generated from code repository analysis |
| issue_extraction | Extracted from a linked issue in an external tracker |
Proposal Lifecycle
Change Proposals use a timestamp-based lifecycle — state is derived from two timestamps:
- Pending = exists, neither
applied_atnordismissed_atis set (on the table for review) - Dismissed =
dismissed_atis set (reviewer rejected it; record is retained for dedup) - Applied =
applied_atis set (accepted and enacted)
Dismissed proposals are not deleted — they are retained so the dedup system can recognize when the AI re-discovers the same signal. If the same proposal is later re-surfaced by AI, it is resurrected rather than duplicated. This prevents accumulation of noise while preserving human rejection signals.
Proposals are never batch-applied — each one is applied individually, by a reviewer choosing Apply (or Modify and apply) on that specific proposal. For PRD-driven Initiatives, the Approval → Build stage gate checks that every proposal has been triaged (applied or dismissed) before allowing the transition; it does not do any applying itself, and it also blocks the transition if the PRD’s gap analysis is stale, no requirements are yet in scope, or a captured requirement has no linked tracker issue. This creates a clean demarcation: discovery and proposal-gathering happens in Planning/Approval; locked specifications exist in Build.
Key Fields
| Field | Purpose |
|---|---|
| title | Not a top-level field — a title key can appear inside proposed_changes |
| change_rationale | Why this change is being proposed |
| target_type | Entity type being proposed: requirement, capability, etc. |
| target_id | The entity being updated (for update and connect proposals) |
| proposed_changes | Map of field → new value (for update proposals) |
| snapshot_before | Map of field → current value (before snapshot) |
| source | Where this proposal came from |
| initiative_id | The Initiative this proposal belongs to (optional) |
| application_id | The Application this proposal relates to |
| applied_at | Set when the proposal is accepted and enacted |
| dismissed_at | Set when the proposal is rejected; record retained for dedup |
Reviewing Proposals
The Change Proposals review queue is one of the most important ongoing activities during the Planning and Approval stages of an Initiative. A healthy review cadence:
- Daily: Check for new proposals from overnight AI analysis
- Weekly: Systematic batch review of accumulated proposals
- Stage gate: Complete review before advancing from Approval to Build
For each proposal, a reviewer decides:
- Apply — Accept the change and mark it applied
- Dismiss — Reject the proposal (it is soft-deleted)
- Modify and apply — Edit the proposal content, then apply
Gap Classification and Quality Assessment
Proposals can be annotated with a gap classification (what type of gap the proposal addresses) and a quality assessment (how well-formed the proposed change is). These annotations help triage large volumes of proposals efficiently.
Standalone Proposals
While most proposals are Initiative-scoped, Catalio supports standalone proposals that are not linked to any Initiative. These are useful for:
- Ad-hoc requirement suggestions outside formal engagements
- Changes discovered during routine source monitoring
- Quick proposals generated during live AI sessions
Best Practices
Review proposals within 48 hours of generation.
Proposals lose context rapidly. The team member who triggered the discovery session has the clearest understanding of what the AI extracted — review promptly while that context is fresh.
Dismiss aggressively, apply deliberately.
It is better to have a clean catalog with 80% of the right requirements than a noisy catalog with 120% and 40% noise. Dismiss duplicates, low-confidence extractions, and out-of-scope proposals freely.
Use change_rationale for traceability.
When manually creating proposals, fill in the change_rationale field with why this change is being proposed. Future reviewers (and auditors) benefit from the context.
Finish triage before requesting the Build gate, not ad hoc.
The Planning phase is for discovery and proposal generation. The Approval phase is for review — apply or dismiss each proposal individually as you review it, rather than leaving proposals pending until the last minute. For a PRD-driven Initiative, the Approval → Build stage gate won’t let the transition through while pending proposals remain, so clearing the queue during Approval (rather than piecemeal during discovery) keeps the requirements catalog stable during active specification work.
Use source filtering when reviewing.
When reviewing a large proposal queue, filter by source to review all document_extraction proposals together, all meeting_extraction proposals together. This creates consistent review context.
Relationships at a Glance
| Related Concept | Relationship |
|---|---|
| Initiative | Most proposals belong to an Initiative |
| Application | Proposals are scoped to an Application |
| Requirements | Applied create proposals become Requirements |
| Features | Proposals can be linked to a specific Feature |
| Artifacts | Artifact processing generates artifact_extraction proposals |
| Sources | Source monitoring generates ai_discovery proposals |
Next Steps
- Understand Initiatives — Learn the governance context for Change Proposals
- Upload Artifacts — Trigger
artifact_extractionproposal generation - Connect Sources — Enable ongoing
ai_discoveryproposal generation - Add Requirements — Accept proposals and lock requirements for Build
Pro Tip: At the end of each discovery sprint, sort proposals by source and do a focused 30-minute review session per source type. This is more efficient than reviewing proposals in chronological order and helps you calibrate which sources produce the highest-quality signals.
Support
- Documentation: Continue reading about Initiatives and Requirements
- Email: support@catalio.ai
- Community: Share proposal review workflows with other Catalio users
