Planning flow¶

This is the recommended path for a planner who turns validated specification scope into reviewable planning baselines. Use it when you need a rough effort range in the Plan's selected unit, confidence, readiness signals, factor evidence, and an auditable decision before downstream implementation work starts.

Planning is not delivery scheduling and it is not a commitment. It produces planning guidance from specification artifacts, AI-extracted factors, and the estimation profile selected on the Plan. Humans still decide whether the assessment is credible enough to accept, override, or supersede.

Before you start, make sure Planning is enabled, your role can open Plans, and the target specification already has meaningful Epics, Requirements, and preferably Use Cases. Test Cases are optional, but they improve the test factor. A first walkthrough usually takes 10 to 20 minutes per Planning Scope, depending on how much review the generated assessment needs.

Flow overview¶

Confirm that the specification is ready for planning.
Create or open a spec-scoped Plan.
Review Scope Coverage for each Planning Scope.
Generate a Scope Assessment.
Review the Scope Items breakdown and assessment drivers.
Accept, override, or supersede the assessment.
Generate and review Role Allocation and Specification Allocation.
Generate and review the Plan-level Minimum Baseline.
Project the accepted Minimum Baseline into Feature Candidates.
Review Remaining Scope and create Extensions for later coverage.
Maintain the planning baseline as the specification changes.

Page guides used in this flow¶

Start context: Projects page, Project page, and Plans page
Planning container: Plan detail page
Scope assessment: Planning Scope page
Estimate rules: Tenant Estimation Profiles tab and Tenant Delivery Role Profiles tab
Upstream preparation: Analyst flow
Downstream use: Builder flow

1. Confirm that the specification is ready for planning¶

Pages used: Project page, Specifications page, and Analyst flow

Planning depends on the quality and relationships of the specification artifacts. Before creating or accepting planning estimates, check that the target Epic has enough refined content.

Recommended input quality:

Requirements should be clear enough to classify into UI, backend, data, integration, security, and test factors.
Use Cases should exist when possible. Planning uses Use Cases as the primary scope items because they usually describe coherent behavior.
Requirements that are not linked to any Use Case are still included as fallback rows so they do not disappear from planning.
Test Cases, when present, are used for test-factor classification. If no Test Cases are linked, Planning derives the test factor from Use Cases or fallback Requirements.

What to expect:

incomplete links do not always block assessment generation
weak links produce weaker evidence and lower confidence
missing Test Cases are visible as coverage gaps, not as automatic failures

If the scope is still raw, use the Analyst flow first. The Planning flow is most useful after Requirements and Use Cases are understandable enough for human review.

2. Create or open a spec-scoped Plan¶

Pages used: Plans page and Plan detail page

Open Plans from the top-level navigation or from the project page. A Plan is scoped to one Specification and contains one Planning Scope for each selected Epic.

Use a new Plan when:

the specification has not been planned yet
you need a separate planning container for a new planning cycle
the previous Plan is intentionally being superseded instead of updated

Use an existing Plan when:

you are continuing review for the same Specification and scope set
you need to inspect accepted baselines, assessment history, or timeline activity
you need to add a missing Epic as another Scope

What to expect:

Plans can be edited in any lifecycle state; editing an accepted or superseded Plan reopens it as draft
legacy epic-scoped Plans are view-only in the new spec-scoped Plan detail page
a parent Plan is not fully accepted until every active Scope has an accepted baseline

3. Review Scope Coverage¶

Pages used: Planning Scope page

Open a Planning Scope from the Plan detail page and start in Overview. Review the context tree first so you know which Project, Plan, Scope, and source Epic you are assessing.

In Scope Coverage, check:

source Epic
Scope description
accepted baseline summary, if one already exists
planning item count
Requirement and Use Case coverage
fallback Requirements not linked to Use Cases
Test Case evidence

Use Refresh Coverage when links or source artifacts changed and the coverage summary needs to be recalculated.

Decision guidance:

If the wrong Epic or Scope appears, go back to the Plan before generating an assessment.
If too many Requirements appear as fallback rows, improve Requirement to Use Case links upstream.
If no Test Cases are linked, decide whether derived test classification is acceptable for this estimate.

4. Generate a Scope Assessment¶

Pages used: Planning Scope page

Open the Assessment tab and use Generate. Generation runs in the background. If the page does not update immediately, click the AIKOZO logo in the top bar and use Background jobs to confirm whether the job is queued, running, completed, or failed.

What generation produces:

separate Full Scope and Active Scope analyses, each with readiness, confidence, drivers, missing information, and a min/most-likely/max estimate
a zero Active Scope estimate when every Scope Item is deferred
classifications for every Scope Item, including deferred items
a canonical deterministic effort split: active effort across active items and the Full-minus-Active delta across deferred items, with exact reconciliation
estimation profile key, version, and snapshot information when available

Generation does not accept the estimate automatically. The generated assessment is a review candidate until a Planner or Admin accepts it.

5. Review Scope Items and assessment drivers¶

Pages used: Planning Scope page

Use the Scope Items tab to answer: "What is this scope broken into?"

Each row represents either:

a primary Use Case, or
a fallback Requirement when that Requirement is not linked to any Use Case

For each row, review:

UI, backend, data, integration, security, and test factor levels
evidence text explaining why the factor levels were assigned
factor pills, where Admins and Planners can click the left half to decrease a factor level or the right half to increase it
the combined Decision detail with provenance and reason
the combined Effort detail with canonical Full and Active contributions
the Defer or Restore action when a scope item should move out of, or back into, active planning scope without editing the source artifact; both actions require a reason

Each Scope Item uses a two-row group. The item label and Action span both rows; the first row contains Decision, Effort, and Evidence, while the second row shows all six factors across one merged detail cell. Linked Requirement and Test Case counts are omitted so the decision-focused data fits without horizontal scrolling.

Changing any item factor recalculates that item's canonical Full and Active effort contribution and rolls the delta into the Scope estimates. Contributions of other Scope Items remain unchanged; effort is not redistributed to preserve the previous total. Setting a factor to none therefore removes that factor's calibrated contribution from the item. Existing allocations and downstream Minimum Baselines are marked stale for audit. They remain usable, but may not reflect the changed factor values.

Then return to Assessment and review the generated readiness, effort, confidence, effort drivers, risk drivers, and missing information.

Deferring a Scope Item is a planning-domain decision only. It stores a durable overlay on the Planning Scope, leaves Requirements, Use Cases, and Test Cases unchanged, and marks accepted planning outputs stale. Those outputs remain usable; the freshness warning explains that they may not reflect the latest decision. The UI does not claim an immediate saving before the Active Scope estimate is regenerated and reviewed.

Decision guidance:

high effort with weak evidence should be reviewed carefully before acceptance
missing information is a planning risk, not just a note
low confidence is a signal to improve source artifacts or add a review note
Scope Items are classification evidence, not the Effort Allocation output

6. Accept, override, or supersede the assessment¶

Pages used: Planning Scope page

Use the review actions only after checking the generated assessment and Scope Items evidence.

Available decisions:

Review: add a review note without making the assessment the baseline.
Accept: make this assessment the current planning baseline for the Scope.
Override: replace either or both generated Full/Active estimates with one required justification. Active min/likely/max may never exceed Full.
Supersede: retire the assessment when it should no longer be considered current.
If the newest assessment is already superseded but an accepted baseline still exists, Supersede targets that accepted baseline so the Scope no longer blocks Plan-level unit changes.

What to expect after acceptance:

the accepted assessment becomes the Scope baseline
previous accepted assessments for the same Scope are superseded
the parent Plan rollup is recomputed
freshness warnings appear when inputs changed; they are informational and do not block planning actions
the assessment remains auditable in history and filterable timeline details

Accept only when the estimate is credible for planning. Override only when the human correction is deliberate and the justification would make sense to a later reviewer.

7. Generate and review Role Allocation and Specification Allocation¶

Pages used: Planning Scope page

Open Roles after an assessment has been accepted to generate and review the role split. Until then, the page shows Accept an assessment before role allocation. Open Allocation for the specification artifact split; until an assessment is accepted it shows Accept an assessment before allocation.

The Planning Scope page has two allocation views:

Role Allocation first divides every active Scope Item contribution across its six non-none factors, then divides each factor bucket only among roles eligible for that factor. Delivery Role Profile weights and factor adjustments determine the split inside each bucket. A none factor contributes zero; for example, when every test factor is none, no Tester role is allocated. It does not create independent role estimates. The profile key, version, snapshot, factor allocation, and factor reconciliation are stored for audit.
Specification Allocation selects a Full or Active basis (Active by default). Full includes all lineage; Active excludes deferred lineage. It is an optional artifact view, not a Minimum Baseline prerequisite.

Use Generate Allocation on Roles when you need a role split for planning and review. Use Generate Allocation on Allocation when you need traceable effort guidance by specification artifact. Both paths reconcile back to the accepted Scope estimate, so the sum of allocated role effort matches the sum of allocated specification effort for the same accepted assessment.

Review:

accepted assessment estimate and Plan-associated Delivery Role Profile
factor-proportional role shares, effort ranges, factor rationale, confidence, the factor-to-role effort matrix, and CSV export when needed. Matrix rows are factor effort buckets, columns are delivery roles, and role totals are column sums. Hover a matrix row label or its level counts to see that the counts are active Scope Items at each factor level and that their effort is shared across eligible roles. Deferred Scope Items are excluded from these counts. The CSV contains the same factor-bucket and role-contribution values. The compact matrix headers use BE Developer and FE Developer.
allocation target: automatic, Use Cases, Requirements, or Test Cases
allocation method: factor weighted or equal
total allocated effort
reconciliation status
linked artifact rows, final text, item weights, factor effort buckets, and CSV export when needed

What to expect:

if no role allocation exists yet, the page says No role allocation generated yet.
if no allocation exists yet, the page says No allocation generated yet.
generated role allocation and specification allocation totals should reconcile to the accepted estimate
Factor-weighted Specification Allocation and Role Allocation use the same canonical factor-effort-bucket calculation. Generation stops explicitly when an active Scope Item has missing/invalid factors, all six factors are none while the item has effort, or canonical item effort does not reconcile to Active Scope; no equal fallback is applied
small rounding residuals are applied to the final item
each item shows factor effort buckets across UI, backend, data, integration, security, and test; low/medium/high classifications redistribute the item allocation while preserving the item total
accepted allocations are planning guidance, not delivery commitments

8. Generate and review the Minimum Baseline¶

Pages used: Plan detail page

After each active Scope has a current accepted dual assessment, return to the Plan detail page and open Minimum Baseline. Specification Allocation is not required. Use Generate to create an immutable deterministic revision from the accepted assessments and canonical Scope Item splits. This does not call AI and it does not delete or change Requirements, Use Cases, Test Cases, Scope Assessments, or allocations. It stores a snapshot so later source edits do not rewrite historical baselines.

Classifications:

included: mandatory or core evidence exists, such as high or critical priority, accepted/final core workflow evidence, security, audit, compliance, or explicit required language.
required dependency: the artifact supports an included item through Requirement, Use Case, Test Case, or approved dependency graph links.
Deferred from this Minimum Baseline: explicit optional, nice-to-have, secondary, reporting, or advanced-filtering evidence exists and no mandatory or dependency evidence exists.
excluded: explicit out-of-scope, obsolete, deprecated, or cancelled evidence exists.
decision needed: allocation or assessment data is missing, evidence conflicts, compliance/security ambiguity exists, or evidence is insufficient. Silence alone does not defer an item.

Reconciliation applies to min, most-likely, and max:

Full Scope = Active Scope + explicit planner-deferred effort
Active Scope = Minimum Baseline + baseline-deferred + excluded + decision-needed
Planned reduction includes explicit deferred, baseline-deferred, and excluded effort; it never includes decision-needed effort
incomplete cost or a non-zero residual blocks acceptance

The four compact summary cards present Full Scope, current Active Scope, the current Minimum Baseline target, and Planned reduction with a prominent range and a separate most-likely value.

The Scope reconciliation section separates effort disposition from arithmetic. Five compact breakdown tiles show the effort and item count held in the Minimum Baseline, then moved by planner deferrals, suggested or accepted deferrals, exclusions, and unresolved decisions. Supporting audit information is grouped under Baseline details so the primary estimates and decisions remain easy to scan. Expand it to see source assessments, classification counts, review notes, and separate Full Scope balance and Active Scope balance checks. They show a green Balanced state when the corresponding residual is zero; a non-zero residual is highlighted as a variance that needs review. This keeps unresolved effort visible without presenting it as a planned reduction.

Suggested for later and Excluded use the immutable Minimum Baseline revision. Deferred by planner uses current Scope Item decisions and sums their canonical Full Scope contributions. The current Active Scope, Minimum Baseline estimate, Planned reduction, and In Minimum Baseline card are projected from those current deferrals. Decision needed uses open Savings Opportunities whose backend validation is decision_needed, summing the indicative ranges that are available. Its helper text states how many opportunities have quantified effort. Applied opportunities leave this bucket and are represented by the resulting deferred Scope decisions. Balance checks continue to use immutable revision totals.

Acceptance may continue with decision-needed effort only after warning confirmation. Generated, reviewed, and accepted revisions are immutable. Decision or coverage changes mark them stale for audit, but do not require a new revision before continuing. Generate a new revision when the latest inputs need to be reflected.

The canonical unit is person_days or person_hours. Every reconciliation bucket retains the assessment profile unit; the UI displays these as person-days or person-hours without converting between them.

Use Review when the generated baseline has been checked, Accept to make it the current Minimum Baseline for the Plan, and Supersede when the baseline should no longer be current. Accepting a new Minimum Baseline supersedes the previous accepted Minimum Baseline for the same Plan. Superseding is not deletion; old baselines remain audit records.

Open Design verification and use Generate in Design-informed Confidence when a final Implementation Design exists and you want to check whether the Minimum Baseline is still credible against the architecture. The review reads persisted Implementation Design fragments and the Patterns selected or allowed by that Design. It does not read Flow Designs, Features, Execution Targets, Action Packs, Instruction Sets, Build Runs, JIRA tasks, or implementation tasks, and it does not mutate Design or Pattern records.

The Design-informed Confidence result stores architecture fit, Pattern fit, reuse evidence, architecture-related effort and risk drivers, missing architecture information, baseline realism notes, referenced Design fragments, referenced Patterns, recommended confidence, and whether confidence should increase, decrease, or stay unchanged. Recommended confidence is guidance for human planning review; it does not recalculate effort, overwrite accepted Scope Assessments, overwrite accepted allocations, or change the accepted Minimum Baseline. Planner and Admin roles can generate, review, accept, supersede, or refresh these reviews. Accepted reviews create an auditable confidence checkpoint before the later Feature Projection phase.

Design-informed Confidence generation runs as a background job. Open Background jobs from the AIKOZO logo to see whether the Design Confidence job is queued, running, completed, or failed. When the job finishes, refresh the Design verification tab if the review has not updated yet.

The Minimum Baseline tab can also generate Savings Opportunities for an existing Minimum Baseline. These are AI-assisted suggestions that answer where the Plan might reduce implementation effort while preserving required scope. They do not replace deterministic baseline generation: AI only proposes candidates, and the backend validates artifact references, mandatory scope protection, dependency protection, classification safety, tenant/project scope, and all saving calculations before anything is shown.

Use Generate to queue the AI prompt as a background job. The button shows Generating... while the job is being started. Open Background jobs from the AIKOZO logo to see whether the Minimum Baseline savings job is queued, running, completed, or failed. When the job finishes, refresh the Minimum Baseline tab if the table has not updated yet.

Savings Opportunities can use these suggestion types:

defer: move clearly optional scope out of the Minimum Baseline.
reduce: narrow clearly optional scope while keeping required behavior.
split later: keep required behavior now and move secondary behavior later.
decision required: highlight ambiguity that a Planner or Admin must resolve before treating it as a saving.

Each opportunity is tied to artifacts already present in the Minimum Baseline or accepted allocations. Savings are calculated only from existing allocation item estimates and are shown as Indicative saving. If an artifact is mandatory, security/compliance/audit critical, a required dependency, part of an accepted core workflow, or unclear, the backend can still show the indicative effort attached to the affected artifact while marking the opportunity decision needed. If an artifact has no allocation estimate, there is no indicative saving to show. Opportunity suggestions do not delete, defer, or mutate Specification artifacts; Planner/Admin review remains required.

When a Savings Opportunity maps affected artifacts unambiguously to Planning Scope items, Defer all records the decisions and marks the opportunity applied. It never rewrites the source Minimum Baseline. A stale accepted baseline may still be used for Savings, Design Confidence, Feature Projection, and Extension generation/apply actions. The UI keeps the freshness warning visible because those outputs may use older inputs.

9. Project Feature Candidates¶

Pages used: Plan detail page

After a Minimum Baseline is accepted, open Feature Candidates. This tab answers which Implementation Features should be created from the accepted baseline. Generate queues a background AI job that creates a Feature Projection Proposal from the accepted Minimum Baseline, Baseline Items, linked Requirements, Use Cases, Test Cases, accepted Specification Allocation, Role Allocation evidence when available, the accepted Design verification result, Implementation Design fragments, and the Patterns selected or allowed by that Design. Track the job in Background jobs; the tab refreshes after the job completes.

Feature Candidates are not Flow Designs, Action Packs, Instruction Sets, delivery tasks, execution routing, or code. They are reviewable implementation feature boundaries with traceability back to the Plan, Minimum Baseline, proposal, candidate, Baseline Items, Scopes, Requirements, Use Cases, Test Cases, Design fragments, and Patterns.

The tab shows proposal status, coverage summary, unassigned Baseline Items, inherited effort, and the generated Feature Candidate list. Warnings are grouped in a collapsed disclosure with a visible count; expand it to review validation and traceability concerns. Open a candidate to review the Feature Candidate detail page. Its tabs separate Risks and decisions, Included in scope, Required dependencies, and Design fragments. The detail page also shows additional traceability to Requirements, Use Cases, and Test Cases, plus Patterns and created Feature links after apply. Unassigned Baseline Items are eligible accepted-baseline items that were not placed into a Feature Candidate; review them before accepting a proposal.

Planner and Admin roles can generate, review, accept, and supersede Feature Projection Proposals. Apply is restricted to Admin in the current UI/API. Apply only works in two safe modes:

create a new Implementation and create Features there
use an existing Implementation only when it has no Features

Feature Projection protects populated Implementations. If the selected Implementation already contains Features, apply is rejected, no Feature is created, and existing Features are not overwritten or merged. Applying a proposal never mutates the accepted Minimum Baseline, Specification artifacts, Design artifacts, Pattern definitions, Flow Designs, Action Packs, Instruction Sets, or execution artifacts.

10. Review Remaining Scope and Extensions¶

Pages used: Plan detail page

After Feature Projection has been applied, open Remaining Scope. The tab compares Plan Scope lineage with created Implementation Feature traceability to show what has already been projected and what remains outside the projected Implementation. Coverage is calculated from applied Feature source references, not manual checkboxes.

The dashboard shows projected Requirements, Use Cases, Test Cases, and effort where allocation estimates are available. Effort coverage uses stored planning allocation and baseline estimates; if some artifacts lack numeric effort, the tab still shows count coverage and displays a warning instead of inventing an estimate.

Artifact states mean:

projected: already covered by created Features from applied projections
remaining: eligible for a later Extension
deferred: intentionally deferred in planning
decision_needed: blocked until a planner records a decision
excluded: explicitly excluded from the current baseline
blocked: missing traceability, allocation, or other prerequisite data

Planner and Admin roles can select remaining or deferred artifacts and create an Extension. Extension items keep their source Scope, baseline item when available, allocation estimate, and original artifact snapshot. Already projected artifacts cannot be selected again, and artifacts outside the Plan lineage are rejected by the backend.

An accepted Extension can generate its own Feature Projection Proposal using the same Feature Candidate mechanism as the Minimum Baseline, but with source_type recorded as extension. Extension projection preserves traceability to the Plan, Extension, Extension Items, source baseline items when available, Scopes, Requirements, Use Cases, Test Cases, Design fragments, and Patterns. It does not create Flow Designs, Action Packs, Instruction Sets, execution artifacts, or implementation tasks.

Applying an Extension differs from applying the Minimum Baseline. Baseline projection can still apply only to a new Implementation or an existing Implementation without Features. Extension projection may also apply to an existing populated Implementation only when every existing Feature is traceable to prior accepted or applied Feature Projections from the same Plan. The backend rejects unrelated, mixed, untraceable, or duplicate artifact targets atomically.

11. Maintain the baseline as scope changes¶

Pages used: Plan detail page, Planning Scope page, Tenant Estimation Profiles tab, and Tenant Delivery Role Profiles tab

Planning is a baseline, not a one-time file export. Revisit the Plan when the underlying specification changes materially.

Regenerate or review again when:

Requirements or Use Cases are added, removed, or substantially rewritten
links between Requirements, Use Cases, and Test Cases change
missing information is resolved
risk or effort drivers no longer match current understanding
a new accepted baseline should supersede the old one
the accepted Minimum Baseline no longer reflects current accepted Scope evidence

Use Assessment history, the Planning Scope Timeline, and Plan Versions to reconstruct what changed and why. Current Planning panels hide superseded assessments, allocations, and Minimum Baselines by default so retired candidates do not clutter the active workflow. Use Estimation Profiles on the Tenant page when you need to inspect which deterministic profile version is associated with the Plan for future assessments. Changing the tenant default only changes the preselected profile for new Plans; it does not rewrite existing Plan profile references. Use Delivery Role Profiles on the Tenant page when you need to inspect or manage the deterministic role weights available for Plans. Changing the tenant default only changes the preselected delivery role profile for new Plans; existing Plans and Role Allocations keep their stored profile references and snapshots.

Completion checklist¶

The Planning flow is complete when:

every active Scope in the Plan has reviewed coverage
every active Scope that needs planning has an accepted assessment baseline
overrides, if any, include clear justification
Scope Items evidence has been checked for weak or surprising classifications
Role Allocation or Specification Allocation has been generated and accepted when that allocation guidance is needed
the Plan-level Minimum Baseline has been generated and accepted when minimum scope optimization guidance is needed
Design-informed Confidence has been generated and reviewed when a final Implementation Design should inform planning confidence before Feature Projection
Remaining Scope has been reviewed after Feature Projection apply when the team needs a path from the Minimum Baseline toward fuller coverage
the team understands that the output is planning guidance, not a delivery commitment