Complex Project Definition and Planning

A structured methodology for projects with significant uncertainty, architectural decisions, or multi-repository scope. The workflow produces three living documents through iterative dialog and explicit decision rounds, ensuring all ambiguities are surfaced and resolved before implementation begins.

For simpler, well-defined work, use the Project Planning Workflow instead.

When to Use This Workflow

Factor	Complex Project Planning	Project Planning
Uncertainty	High — multiple viable approaches	Low — clear path forward
Scope	Multi-repo or multi-component	Single repo or contained change
Decisions needed	3+ design decisions with trade-offs	0-2 straightforward choices
Output	Design + Plan + Decision Log	Specification + Requirements + Verification
Process	Iterative dialog with decision rounds	Single-pass generation from goal file
Typical size	15+ tasks, 3+ phases	1-15 tasks, 1-2 phases

Three-Document Pattern

This workflow produces three separate documents in the project directory:

Document	File	Template
Design	design.md	Design Document template
Decision Log	decision-log.md	Decision Log template
Project Plan	project-plan.md	Structure defined below (extends Project Planning)

The three documents cross-reference each other: the design references DQ numbers from the decision log, the project plan references design sections for context, and the decision log records which documents were updated when each decision was applied.

---

Workflow

Phase 1: Context Gathering

Goal: Build shared understanding before designing.

1. Read reference materials. Read all files and repositories referenced in the initial request fully — do not skim. You need to understand the existing architecture before proposing a design.

2. Produce a summary. Write a concise summary (1 page max unless instructed otherwise) of:

   • The existing architecture relevant to the requirement.
   • The goal or requirement as you understand it.
   • Any constraints or boundaries stated by the team.

3. Get confirmation. Share the summary and wait for confirmation or corrections before proceeding to design. This step prevents wasted effort caused by misunderstood scope.

Phase 2: Design with Alternatives

Goal: Present design options, not a single solution.

1. Identify design options. Present at least two viable approaches with:

   • A concise description of each approach.
   • Trade-offs: complexity, maintainability, testability, backward compatibility.
   • Impact on existing code.

2. Recommend one option with clear rationale, but frame it as a recommendation, not a decision.

3. Wait for the team’s choice. The responsible engineer or tech lead selects an option, possibly with modifications. Do not proceed to document creation until a direction is chosen.

Phase 3: Three-Document Creation

Goal: Produce the initial versions of all three documents.

Prerequisite: The team has confirmed the design direction and explicitly requested artifact creation. Do not produce documents while still in consultative discussion.

1. Create design.md following the Design Document template:

   • Include class diagrams, sequence diagrams, and API contracts.
   • Mark design choices that need further resolution as “Pending DQ-NNN”.

2. Create project-plan.md with:

   • Phased task list (see Project Plan Structure below).
   • Dependency graph (PlantUML).
   • Persona assignments.
   • Worktree strategy (if multi-agent).

3. Create decision-log.md following the Decision Log template:

   • Populate Round 1 with all open questions identified during design.
   • Include options, trade-offs, and recommendations for each.

Phase 4: Decision Rounds

Goal: Iteratively resolve all open questions.

1. Share the decision log with the team for review.
2. The responsible engineers make decisions (choosing options, possibly with modifications).
3. Apply each decision to design.md and project-plan.md:
   • Update diagrams, class descriptions, task lists.
   • Update the Decision Summary table in the design document.
4. Review updated documents for new ambiguities.
5. If new questions arise, add Round N+1 to the decision log and repeat.
6. Continue until no new questions arise.

Decision rounds are not a sign of incomplete work — they are the mechanism by which complex design gets resolved incrementally. Expect two to four rounds for most complex projects.

Phase 5: Release Planning (Multi-Repo Projects)

Goal: Define the release process for changes spanning multiple repositories.

For multi-repo projects, the project plan must include:

1. CHANGELOG update tasks — one per repository, explicitly listed.
2. PR lifecycle tasks — per-repository sequence covering review, approval, and merge.
3. Merge ordering — explicit dependency chain for PR merges (upstream repos before downstream consumers).
4. Composite build revert tasks — if worktrees or includeBuild were used during development, steps to revert local path overrides before opening PRs.
5. Push guards — safety instructions for avoiding accidental pushes of local override configurations.

See Release Lifecycle conventions for the full per-repository release sequence.

Phase 6: Plan Finalization

Goal: Ensure the plan is ready for execution.

1. Verify all DQ entries are Decided or explicitly Deferred.
2. Verify the project plan has no placeholder tasks or TBD items.
3. Validate all PlantUML diagrams render correctly.
4. Ensure cross-references between the three documents are consistent.

A plan with open DQ entries or placeholder tasks is not ready for team execution. Resolve or explicitly defer every open question before handing off to an implementing team.

---

Project Plan Structure

The project-plan.md produced by this workflow uses the following format:

# Project Plan: <Project Name>

## Overview

<2-3 sentences. Reference the design document for detailed architecture.>

## Repositories

| Repository | Role | Branch |
|------------|------|--------|
| `<repo>` | <upstream/downstream/test> | `<branch-name>` |

## Phases

### Phase N: <Phase Name>

**Entry criteria**: <conditions that must be true>

| # | Task | Repository | Depends On | Acceptance Criteria |
|---|------|-----------|------------|---------------------|
| T-01 | <task> | `<repo>` | -- | <criteria> |
| T-02 | <task> | `<repo>` | T-01 | <criteria> |

**Exit criteria**: <conditions including build/test passing>

### Phase N+1: Release

(CHANGELOG updates, version catalog, PRs, and merge ordering)

## Dependency Graph

(PlantUML dependency diagram)

## Personas

| Persona | Working Directory | Agent Name Pattern |
|---------|------------------|--------------------|
| <role> | `<path>` | `<prefix>-<description>` |

## Worktree Strategy

(Worktree naming, branch names, integration branch, cleanup steps)

---

Cross-Repository Checklist

At the start of any multi-repo project, answer these questions before designing:

1. What is the repository dependency chain?
2. How does local development resolve cross-repo dependencies (composite builds, local overrides)?
3. Will worktrees be used? Do composite build paths need adjustment per worktree?
4. What version catalog entries need updating when dependencies change?
5. Are there CI/CD pipelines that must pass between PR merges?

Surface any unclear answers as DQ entries in the decision log. Do not defer these to implementation — they affect task ordering and cannot be resolved mid-execution.

---

What Makes a Good Initial Request

When starting a complex project session, include these elements to get the most out of the workflow:

Element	Purpose	Example
Goal statement	One sentence, what the feature does	”Enable an Inventory Endpoint”
Reference pointers	Specific repos, files, or docs to read	common-module, operations
Explicit constraints	Boundaries and non-goals	”All machinery in common-module”
Exclusions	What NOT to include	”Drop environment info”
Output scope	How much to produce initially	”Give me a summary, 1 page max”
Mode	Consultative vs. artifact production	”Discussion only, no changes yet”

Providing a clear mode instruction (“discussion only” vs. “produce artifacts now”) is particularly important. Without it, an engineer facilitating the session may proceed to document creation before the team has reached consensus.

---

Related Pages

• Project Planning Workflow — the lighter-weight sibling for well-defined projects
• Project Decomposition — framework for splitting large plans into sequenced runs
• Decision Log template
• Design Document template

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved