Skip to content

workflow-state-machine.md

Latest commit

 

History

History
112 lines (76 loc) · 5.29 KB

workflow-state-machine.md

File metadata and controls

112 lines (76 loc) · 5.29 KB

Workflow State Machine

Valid Status Values (ONLY these are allowed)

CRITICAL: The status field in prd.json MUST be one of these exact values. Using ANY other value (e.g., "pr_created", "in_review", "ready", etc.) is INVALID and will break the workflow.

Status Type Description
"pending" Active Development in progress
"committed" Active Code committed locally, ready to push and create PR
"pushed" Active PR created and public, awaiting review/merge
"merged" Terminal PR merged successfully
"skipped" Terminal Intentionally skipped (e.g., duplicate PR exists)
"invalid" Terminal Invalid story, won't be worked on

Valid transitions: pending → committed → pushed → merged. Any status can also transition to skipped or invalid. The pushed state loops back to itself when responding to review feedback.

NEVER invent new status values. If a transition doesn't fit one of these statuses, you are misunderstanding the workflow.

Your Task - State Machine Workflow

CRITICAL: One Story Per Iteration

The story to work on is pre-selected by scripts/select-task.py and provided in the prompt. You do NOT need to do task selection — just execute the workflow for the assigned story.

Each iteration:

  1. Execute the workflow for the assigned story's status
  2. Update the PRD and progress.txt
  3. END THE ITERATION - Stop processing

Handling Duplicate Test Fix Stories

CRITICAL RULE: Never skip a test fix story as "duplicate" if the GitHub issue is still open

When multiple stories exist for the SAME test (same testFilter value):

Decision Logic - Default to NOT skipping

If the GitHub issue is still OPEN → DO NOT SKIP (assume re-occurrence)

An open issue means the test is still failing. Treat subsequent stories as NEW fix attempts, not duplicates.

When to Skip (requires ALL conditions)

Only skip a test fix story as "duplicate" if ALL of these are verified:

  1. Previous fix is merged (not just open/under review)
  2. GitHub issue was created BEFORE the previous PR merged
    • Compare timestamps: issue.createdAt < pr.mergedAt
    • If issue was created AFTER the merge, this is a RE-OCCURRENCE → work on it
  3. No new failures reported since the merge
    • Check issue comments for reports of continued failures
    • Check CI/build logs if available
  4. Version/environment matches (if specified in the issue)
    • If the issue mentions a specific Chromium version, verify the fix covers that version

Timestamp Verification Commands

# Get issue creation date
gh issue view <issue-number> --repo $ISSUE_REPO --json createdAt

# Get PR merge date
gh pr view <pr-number> --repo $PR_REPO --json mergedAt

# Compare: If issue.createdAt > pr.mergedAt → RE-OCCURRENCE (work on it)

Example

US-016 and US-023 both fix BraveSearchTestEnabled.DefaultAPIVisibleKnownHost:

  • US-023 has PR #33596 merged on 2024-01-15
  • US-016's issue was created on 2024-01-20 (AFTER the merge)
  • This is a RE-OCCURRENCE → US-016 should be worked on as a NEW fix attempt
  • Do NOT skip US-016 - the previous fix did not address all failure modes

Important Notes

  • When in doubt, DO NOT SKIP - intermittent tests often have multiple root causes
  • Each fix story may address different race conditions or timing issues
  • A merged PR does NOT guarantee the intermittent test is fixed
  • Only skip after VERIFICATION using timestamp data that proves it's a true duplicate
  • If timestamps are unavailable or ambiguous, proceed with implementation

State Change Tracking

The lastIterationHadStateChange field in run-state.json controls whether the work iteration counter increments. This keeps the iteration count meaningful (representing actual work done) while allowing rapid checking of multiple stories without inflating the count.

  • Set to true when a story's status changes (pending→committed, committed→pushed, pushed→merged, or review response with push)
  • Set to false when checking a story but making no changes (test failures, waiting for reviewer, blocked states)

This allows the system to check multiple pushed PRs rapidly without incrementing the work iteration counter for each one, while still using a fresh context for each check.

Execute Workflow Based on Status

Execute the workflow based on the story's current status:

Task Selection (Handled by Script)

Task selection is handled deterministically by scripts/select-task.py — the selected story is provided in the prompt. See run-state-management.md for configuration options (skip pushed tasks, merge backoff, etc.).

Error Handling

GitHub CLI (gh) Failures:

  • If any gh command fails, log the error and abort immediately
  • Do NOT attempt workarounds or continue without the gh operation
  • Document the failure in $BOT_DIR/data/progress.txt (story remains at current status)