# Workflow Simplification Audit

## Summary

The workflow is now coherent enough to support disciplined AI engineering, but it is close to becoming over-modeled. The canonical state model and prompt synthesis standard solved two major sources of drift: state interpretation and prompt construction. The next step should not be more roles. It should be fewer decision paths, stronger readiness gates, and clearer helper-driven transitions.

The current system can support the intended flow, but humans still need to know which helper or role to invoke at each point. The strongest simplification opportunity is to make the helpers say the next action from canonical state, then have Telegram and Orchestrator follow that state instead of each keeping separate interpretations.

## Simulated Flow

1. Rough idea
   - Requirements Intake receives incomplete input.
   - It creates or revises a requirements file with `new-requirements.sh`.
   - Risk: intake role and requirements template duplicate several checklist items.

2. Requirements intake
   - Intake fills user perspective, workflows, scope, assumptions, open questions, acceptance criteria, and risks.
   - `requirements-state.sh` can report missing sections.
   - Risk: state helper does not yet report canonical requirements state names from `workflow-state.md`.

3. Requirements review
   - Requirements Review applies `requirements-gates.md`.
   - `approve-requirements.sh` blocks approval without current PASS.
   - Risk: approval checks PASS, but not all requirements gates or stale review rules.

4. Chunk planning
   - Chunk Planner consumes approved requirements and writes chunk plan.
   - Risk: no helper validates that chunk plan exists before completing requirements.

5. Orchestration
   - Orchestrator routes Developer -> QA loops and owns completion.
   - `workflow-state.sh` reports canonical chunk state.
   - Risk: `orchestrator-next.sh` still gives generic advice and does not consume canonical state deeply.

6. Developer pass
   - Developer updates Execution Notes and Developer Pass.
   - `workflow-state.sh --ready-for-qa` can verify readiness.
   - Risk: Developer and QA role docs repeat state/pass expectations that could point to a single standard instead.

7. QA pass
   - QA updates QA Review and QA Pass.
   - `workflow-state.sh --ready-to-complete` checks completion readiness.
   - Risk: stale QA Review handling still relies on role discipline after Developer changes.

8. Completion gate
   - `workflow-state.sh --ready-to-complete` now reports `Completion gate: passed|blocked`.
   - This is the clearest current enforcement point.
   - Risk: `complete-chunk.sh` does not call the readiness gate, so a user can still bypass it.

9. Commit ready
   - After completion/archive, git status remains dirty.
   - `workflow-state.sh` can report `commit_ready` when no active chunk exists and git is dirty.
   - Risk: commit readiness is not yet integrated into Telegram or Orchestrator helper output.

10. Final human review
   - Human reviews status and diff before commit.
   - Risk: no consolidated "final review packet" helper exists.

## Simplification Findings

- Keep canonical state as the primary abstraction. Do not add more independent workflow interpretations.
- Avoid adding Repo Analysis and Solution Architect as always-on roles. They should be optional patterns or templates until a product feature proves they are needed.
- Keep Prompt Synthesizer, but treat it mostly as a standard and fallback role. A separate role is justified only because prompt generation has safety and stale-state concerns.
- Reduce duplicated instructions by moving pass-history, stale-review, and readiness rules into standards, then making role files refer to those standards instead of restating details.
- Merge "what to do next" logic into read-only helpers. `orchestrator-next.sh` should consume `workflow-state.sh` and `requirements-state.sh`.
- Make completion helpers enforce readiness instead of relying only on docs.

## Duplicated Responsibilities

- Orchestrator, chunk README, and workflow-state standard all describe Developer -> QA loop behavior.
- QA role, QA template, and done/qa-gates repeat runtime smoke and cleanup expectations.
- Requirements Review role, requirements review template, requirements standard, and requirements gates repeat review criteria.
- Telegram README and prompt synthesis standard both describe prompt safety boundaries.

Duplication is not yet harmful, but future changes should update standards first and shorten role files.

## Role Decisions

| Role | Decision | Reason |
| --- | --- | --- |
| Requirements Intake | Keep | Clear responsibility for rough idea normalization. |
| Requirements Review | Keep | Separate approval gate before chunk planning is useful. |
| Chunk Planner | Keep | Converts approved requirements into implementation units without coding. |
| Orchestrator | Keep | Owns sequencing, completion, and manual intervention. |
| Developer | Keep | Single scoped implementation owner. |
| QA | Keep | Separate validation and approval owner. |
| Prompt Synthesizer | Keep, but use sparingly | Safety-sensitive prompt construction benefits from a standard; role is useful for complex prompt handoffs. |
| Repo Analysis | Postpone | Current Orchestrator/Developer can inspect repo for small chunks. Add only when larger product requirements need repeatable read-only discovery. |
| Solution Architect | Postpone | Current Requirements Review plus Chunk Planner can cover most design decisions. Add only when cross-layer architecture decisions become too large for chunk planning. |

## Missing Enforcement Helpers

- `complete-chunk.sh` should call `workflow-state.sh --ready-to-complete` or provide an explicit override requiring human confirmation.
- `orchestrator-next.sh` should report canonical state and recommended next action from `workflow-state.sh`.
- `requirements-state.sh` should report canonical requirements state.
- `approve-requirements.sh` should check stale Requirements Review and key requirements gates, not just PASS.
- `complete-requirements.sh` should check chunk plan state or require an explicit superseded reason.

## Fragile Markdown / State Interactions

- Markdown is still parsed with shell/awk conventions. Heading changes can break helpers.
- Current state depends on role discipline to update Execution Notes, QA Review, Requirements Review, and Pass History together.
- Stale-state detection exists for chunks but is less mature for requirements.
- Completed chunks are immutable by convention, not technically enforced.

The practical mitigation is not a database yet. It is stronger read-only state checks and lifecycle helpers that refuse unsafe transitions.

## Telegram Assessment

Telegram should remain a notification, prompt, and intervention layer. It should not become the workflow engine.

Recommended simplification:

- Let Telegram call shared helpers for workflow state and next action.
- Keep prompt generation aligned with `prompt-synthesis.md`.
- Avoid adding more Telegram-only state rules.
- Keep tmux handoff confirmation-based.

## Recommended Next Chunks

1. `chunk-000033-orchestrator-next-state-integration`
   - Make `orchestrator-next.sh` consume canonical state from `workflow-state.sh`.
   - Output one next action, blockers, and whether human intervention is required.

2. `chunk-000034-completion-gate-enforcement`
   - Make `complete-chunk.sh` refuse completion unless `workflow-state.sh --ready-to-complete` passes.
   - Add an explicit manual override only if policy allows it.

3. `chunk-000035-requirements-state-canonicalization`
   - Extend `requirements-state.sh` to report canonical requirements states from `workflow-state.md`.
   - Add stale Requirements Review detection.

4. `chunk-000036-requirements-approval-gate-enforcement`
   - Make `approve-requirements.sh` check requirements gates and stale review state, not only PASS.

5. `chunk-000037-telegram-shared-state-integration`
   - Update Telegram `/workflowstatus`, `/nextaction`, and completion messaging to consume shared helper output.

## Roles To Avoid For Now

- Do not add Repo Analysis yet.
- Do not add Solution Architect yet.
- Do not split QA into more roles.
- Do not add an automation-executor role until helper gates are enforceable.

## Suggested Immediate Next Step

Implement `chunk-000033-orchestrator-next-state-integration`. It is the lowest-risk simplification because it consolidates next-action logic without mutating lifecycle state.