[plan] [#800] Prompt-First Echo for `acw --chat --stdout`

[were]

Implementation Plan: Prompt-First Echo for acw --chat --stdout

Consensus Summary

Adopt the minimal, low-risk change: print the user prompt earlier without redesigning output streaming. This honors the current stdout contract and provider behavior while fixing the ordering issue. Streaming pipelines are explicitly deferred due to provider output constraints and added failure modes.

Goal

Ensure the user prompt is echoed immediately in chat stdout mode before provider output when stdout is a TTY.

Success criteria:

• The user prompt appears before any assistant output in acw --chat --stdout with TTY.
• Chat history output remains identical to current behavior (no format changes).

Out of scope:

• Streaming assistant output before provider completion
• Provider output routing changes or FIFO/tee pipelines
• However, it it a good idea for future work?
  • ✅ Good to have in the future: A provider-specific streaming pipeline could be added if users explicitly request real-time assistant output and each provider supports stdout/FIFO reliably.

Bug Reproduction

Skip reason (if reproduction not attempted):

• Reproduction was skipped because the issue is clearly visible in src/cli/acw/dispatch.sh control flow and does not require runtime validation to plan the fix.

Codebase Analysis

Files verified (docs/code checked by agents):

• docs/cli/acw.md: Verified current --chat --stdout --editor prompt echo scope and stdout/stderr rules.
• src/cli/acw/dispatch.sh: Verified prompt echo occurs after provider completion in stdout chat mode.
• src/cli/acw/providers.sh: Verified providers write to explicit output paths, limiting FIFO/streaming feasibility.

File changes:

File	Level	Purpose
src/cli/acw/dispatch.sh	medium	Move prompt echo earlier in chat stdout flow (TTY only)
docs/cli/acw.md	minor	Clarify prompt echo timing in --chat --stdout --editor

Modification level definitions:

• minor: Cosmetic or trivial changes (comments, formatting, <10 LOC changed)
• medium: Moderate changes to existing logic (10-50 LOC, no interface changes)
• major: Significant structural changes (>50 LOC, interface changes, or new files)
• remove: File deletion

Current architecture notes:
acw captures provider output to a file in chat stdout mode and echoes the prompt only after provider exit; providers write output to explicit files, not uniform stdout.

Interface Design

New interfaces:

• None.

Modified interfaces:

• None (behavioral timing change only; no new flags or parameters).

Documentation changes:

• docs/cli/acw.md: Update --chat --stdout --editor description to state prompt is echoed before provider output when stdout is a TTY.

Documentation Planning

High-level design docs (docs/)

• docs/cli/acw.md — update prompt echo timing for --chat --stdout --editor to reflect early prompt printing

- With `--chat --editor`: when stdout is a TTY, the editor prompt is echoed to stdout before assistant output.
+ With `--chat --editor`: when stdout is a TTY, the user prompt is echoed immediately before provider invocation, so it appears before assistant output.

Folder READMEs

• None.

Interface docs

• src/cli/acw/dispatch.md — update prompt echo timing rationale for chat stdout TTY path

- Prompt echo occurs after provider completion to keep stdout clean.
+ Prompt echo occurs before provider invocation in chat stdout TTY mode to show user input immediately while preserving clean stdout semantics.

Citation requirement: Command behavior references are grounded in docs/cli/acw.md.

Test Strategy

Test modifications:

• tests/cli/test-acw-chat.sh — ensure prompt precedes assistant output in --chat --stdout --editor with TTY
  • Test case: User Prompt: appears before first assistant token in stdout
  • Test case: output capture still equals provider output contents

New test files:

• None.

Test data required:

• Existing prompt fixture or temp input file already used by chat tests.

Implementation Steps

Step 1: Update documentation for prompt timing (Estimated: 8 LOC)

• File changes:
  • docs/cli/acw.md
  • src/cli/acw/dispatch.md
    Dependencies: None
    Correspondence:
• Docs: Clarifies prompt echo timing and rationale
• Tests: Defines expected ordering to be asserted

Step 2: Add/adjust tests for prompt ordering (Estimated: 15 LOC)

• File changes:
  • tests/cli/test-acw-chat.sh
    Dependencies: Step 1
    Correspondence:
• Docs: Matches the updated prompt timing description
• Tests: Adds ordering assertions for chat stdout TTY behavior

Step 3: Move prompt echo earlier in dispatcher (Estimated: 18 LOC)

• File changes:
  • src/cli/acw/dispatch.sh
    Dependencies: Step 2
    Correspondence:
• Docs: Implements the prompt-first timing described in docs/cli/acw.md
• Tests: Satisfies ordering checks added in Step 2

If is preffered to put some implementation snippets here, if it is less than 20 LoC, use this format:

- if [ "$use_editor" -eq 1 ] && [ -t 1 ]; then
-     echo "User Prompt:"
-     cat "$original_input_file"
-     echo ""
- fi
+ if [ "$use_editor" -eq 1 ] && [ -t 1 ]; then
+     echo "User Prompt:"
+     cat "$original_input_file"
+     echo ""
+ fi
# (Relocated to occur before provider invocation; content unchanged)

Total estimated complexity: 41 LOC (medium)
Recommended approach: Single session

Success Criteria

• Prompt appears before assistant output in --chat --stdout --editor when stdout is TTY
• Chat history content remains unchanged from previous behavior
• Existing chat stdout cleanliness rules still hold

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Prompt echo affects piping behavior	L	M	Keep echo scoped to --chat --editor and TTY only
Ordering test flakiness in TTY contexts	M	L	Use existing test harness patterns for TTY checks
Hidden dependency on old echo timing	L	L	Update docs and tests to match new order

Dependencies

• No new external dependencies; relies on existing shell utilities and test harness.
  Dude, carefully read my response to determine what to do next.