[P1] Analyze → Approve → Format (Hybrid Issue Optimization) - LangChain Issue Intake

[stranske]

Summary

Two-phase issue optimization: LLM analyzes and suggests improvements, human approves via label, system applies suggestions using the Formatter (#1).

Reference

📋 Proposal Document: langchain-issue-intake-proposal.md - See Enhancement #4

Design Philosophy

Eliminates complex stateful conversation in favor of a simple two-phase flow that reuses the Formatter (#478).

Flow

Phase 1: Human labels issue with `agents:optimize`
         → LLM analyzes, posts comment with suggestions + embedded JSON
         → Human reviews suggestions

Phase 2: Human adds `agents:apply-suggestions` label
         → System extracts JSON from comment
         → Routes to Formatter (#1) with suggestions
         → Updates issue body
         → Removes labels, adds `agents:formatted`

Why Hybrid Over Multi-Turn Conversation

Aspect	Original	Hybrid
State management	LangGraph state machine	Stateless - JSON in comment
Human approval	Implicit conversation	Explicit label signal
Implementation	Custom handler	Reuses Formatter (#1)
Complexity	5-7 days	2-3 days

Tasks

• Create scripts/langchain/issue_optimizer.py with analyzer chain
• Create ANALYZE_ISSUE_PROMPT with agent limitations context
• Create suggestion comment formatter with embedded JSON
• Add workflow trigger for agents:optimize label (Phase 1)
• Add workflow trigger for agents:apply-suggestions label (Phase 2)
• Extract suggestions JSON and route to Formatter ([P1] Human → AGENT_ISSUE_TEMPLATE Formatter - LangChain Issue Intake #478)
• Add label management (remove optimize/apply, add formatted)
• Add tests for analyze and apply phases

Acceptance Criteria

• agents:optimize triggers analysis comment with structured suggestions
• Suggestions include task splitting, blocked task identification, objective criteria
• Comment contains <- Updated WORKFLOW_OUTPUTS.md suggestions-json: {...} --> marker
• agents:apply-suggestions extracts JSON and calls Formatter
• Issue body updated with applied improvements
• Labels cleaned up appropriately

Implementation Notes

• Depends on: [P1] Human → AGENT_ISSUE_TEMPLATE Formatter - LangChain Issue Intake #478 (Formatter infrastructure)
• Human questions in comments don't require state tracking
• Known agent limitations documented in proposal

Priority: P1 | Effort: 2-3 days

[github-actions]

Branch codex/issue-518 created from main.

Option 1 (Invite) is enforced on issue events. PR creation is disabled by design so you are the PR author. Codex only engages on human-authored PRs.

Please open the PR as the author so Codex can work on it:

• Compare link: https://github.com/stranske/Workflows/compare/main...codex/issue-518?expand=1
• Suggested title: Codex bootstrap for #518
• Suggested body (copy/paste):

<!-- meta:issue:518 -->

@codex Your objective is to satisfy the **Acceptance Criteria** by completing each **Task** within the defined **Scope**.

## Keepalive Next Task

**This round you MUST:**
1. Implement actual code or test changes that advance at least one incomplete task toward acceptance.
2. Commit meaningful source code (.py, .yml, .js, etc.)—not just status/docs updates.
3. Mark a task checkbox complete ONLY after verifying the implementation works.
4. Focus on the FIRST unchecked task unless blocked, then move to the next.

**Guidelines:**
- Keep edits scoped to the current task rather than reshaping the entire PR.
- Use repository instructions, conventions, and tests to validate work.
- Prefer small, reviewable commits; leave clear notes when follow-up is required.
- Do NOT work on unrelated improvements until all PR tasks are complete.

**COVERAGE TASKS - SPECIAL RULES:**
If a task mentions "coverage" or a percentage target (e.g., "≥95%", "to 95%"), you MUST:
1. After adding tests, run TARGETED coverage verification to avoid timeouts:
   - For a specific script like `scripts/foo.py`, run:
     `pytest tests/scripts/test_foo.py --cov=scripts/foo --cov-report=term-missing -m "not slow"`
   - If no matching test file exists, run:
     `pytest tests/ --cov=scripts/foo --cov-report=term-missing -m "not slow" -x`
2. Find the specific script in the coverage output table
3. Verify the `Cover` column shows the target percentage or higher
4. Only mark the task complete if the actual coverage meets the target
5. If coverage is below target, add more tests until it meets the target

IMPORTANT: Always use `-m "not slow"` to skip slow integration tests that may timeout.
IMPORTANT: Use targeted `--cov=scripts/specific_module` instead of `--cov=scripts` for faster feedback.

A coverage task is NOT complete just because you added tests. It is complete ONLY when the coverage command output confirms the target is met.

**The Tasks and Acceptance Criteria are provided in the appendix below.** Work through them in order.

<!-- 
  DO NOT ADD TASK CONTENT BELOW THIS LINE
  
  Task content is dynamically injected from the PR body via the `appendix` input.
  This template file should only contain instructions, not PR-specific tasks.
  
  If you see task content in this file, it was incorrectly committed and should
  be removed. The guard script will flag this as an error.
-->

[stranske]

Codex belt dispatcher queued this issue and created branch codex/issue-518.

[github-actions]

Branch codex/issue-518 created from main.

Option 1 (Invite) is enforced on issue events. PR creation is disabled by design so you are the PR author. Codex only engages on human-authored PRs.

Please open the PR as the author so Codex can work on it:

• Compare link: https://github.com/stranske/Workflows/compare/main...codex/issue-518?expand=1
• Suggested title: Codex bootstrap for #518
• Suggested body (copy/paste):

<!-- meta:issue:518 -->

@codex Your objective is to satisfy the **Acceptance Criteria** by completing each **Task** within the defined **Scope**.

## Keepalive Next Task

**This round you MUST:**
1. Implement actual code or test changes that advance at least one incomplete task toward acceptance.
2. Commit meaningful source code (.py, .yml, .js, etc.)—not just status/docs updates.
3. Mark a task checkbox complete ONLY after verifying the implementation works.
4. Focus on the FIRST unchecked task unless blocked, then move to the next.

**Guidelines:**
- Keep edits scoped to the current task rather than reshaping the entire PR.
- Use repository instructions, conventions, and tests to validate work.
- Prefer small, reviewable commits; leave clear notes when follow-up is required.
- Do NOT work on unrelated improvements until all PR tasks are complete.

**COVERAGE TASKS - SPECIAL RULES:**
If a task mentions "coverage" or a percentage target (e.g., "≥95%", "to 95%"), you MUST:
1. After adding tests, run TARGETED coverage verification to avoid timeouts:
   - For a specific script like `scripts/foo.py`, run:
     `pytest tests/scripts/test_foo.py --cov=scripts/foo --cov-report=term-missing -m "not slow"`
   - If no matching test file exists, run:
     `pytest tests/ --cov=scripts/foo --cov-report=term-missing -m "not slow" -x`
2. Find the specific script in the coverage output table
3. Verify the `Cover` column shows the target percentage or higher
4. Only mark the task complete if the actual coverage meets the target
5. If coverage is below target, add more tests until it meets the target

IMPORTANT: Always use `-m "not slow"` to skip slow integration tests that may timeout.
IMPORTANT: Use targeted `--cov=scripts/specific_module` instead of `--cov=scripts` for faster feedback.

A coverage task is NOT complete just because you added tests. It is complete ONLY when the coverage command output confirms the target is met.

**The Tasks and Acceptance Criteria are provided in the appendix below.** Work through them in order.

<!-- 
  DO NOT ADD TASK CONTENT BELOW THIS LINE
  
  Task content is dynamically injected from the PR body via the `appendix` input.
  This template file should only contain instructions, not PR-specific tasks.
  
  If you see task content in this file, it was incorrectly committed and should
  be removed. The guard script will flag this as an error.
-->