Implementation Plan: Conversational Ingredient Collection

[Trecek]

Summary

Replace the mechanical "Prompt for input values using AskUserQuestion" instruction — which causes Claude to call AskUserQuestion once per ingredient field — with a conversational block that asks the user what they want to do, infers ingredient values from the free-form response, and only follows up on required ingredients that could not be inferred.

The change touches exactly two text locations: src/autoskillit/cli/_prompts.py (_build_orchestrator_prompt()) and src/autoskillit/server/tools_recipe.py (load_recipe docstring). Both receive identical replacement text. A cross-reference comment establishes the sync contract, satisfying REQ-ALIGN-001 without Python logic changes.

Requirements

PROMPT

• REQ-PROMPT-001: The orchestrator prompt must instruct Claude to ask the user what they want to do conversationally rather than prompting for each ingredient field individually.
• REQ-PROMPT-002: Claude must extract ingredient values from the user's free-form response and only follow up on required values that could not be inferred.
• REQ-PROMPT-003: The ingredient collection instructions must be identical between the cook path (_build_orchestrator_prompt) and the load_recipe tool docstring path.

ALIGN

• REQ-ALIGN-001: The orchestrator behavioral instructions shared between cook and open_kitchen + load_recipe must originate from a single source of truth.

Architecture Impact

Process Flow Diagram

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;

    %% TERMINALS %%
    START([Recipe Loaded])
    DONE([Pipeline Executing])

    subgraph Entry ["Entry Paths"]
        direction LR
        CLIPath["autoskillit cook recipe<br/>━━━━━━━━━━<br/>CLI Entry Point"]
        MCPPath["load_recipe MCP tool<br/>━━━━━━━━━━<br/>Agent calls tool"]
    end

    subgraph Prompt ["● Prompt Construction (modified)"]
        direction LR
        OrchestratorPrompt["● _build_orchestrator_prompt()<br/>━━━━━━━━━━<br/>cli/_prompts.py<br/>Injects --append-system-prompt"]
        LoadRecipeDoc["● load_recipe docstring<br/>━━━━━━━━━━<br/>server/tools_recipe.py<br/>LLM-visible behavioral contract"]
    end

    subgraph Collection ["● Conversational Ingredient Collection (modified)"]
        direction TB
        AskOpen["● Ask open-ended question<br/>━━━━━━━━━━<br/>What would you like to do?<br/>Single question only"]
        Infer["● Infer ingredient values<br/>━━━━━━━━━━<br/>task, source_dir, run_name…<br/>from free-form response"]
        Gate{"● Required values<br/>all inferred?"}
        FollowUp["● Follow-up question<br/>━━━━━━━━━━<br/>Ask only missing required<br/>values in one question"]
        Defaults["Accept optional ingredients<br/>━━━━━━━━━━<br/>Use defaults unless user<br/>explicitly overrode them"]
    end

    Execute["Execute pipeline steps<br/>━━━━━━━━━━<br/>Call MCP tools directly<br/>per recipe step sequence"]

    %% FLOW %%
    START --> CLIPath & MCPPath
    CLIPath --> OrchestratorPrompt
    MCPPath --> LoadRecipeDoc
    OrchestratorPrompt --> AskOpen
    LoadRecipeDoc --> AskOpen
    AskOpen --> Infer
    Infer --> Gate
    Gate -->|"yes — all required inferred"| Defaults
    Gate -->|"no — gaps remain"| FollowUp
    FollowUp --> Defaults
    Defaults --> Execute
    Execute --> DONE

    %% CLASS ASSIGNMENTS %%
    class START,DONE terminal;
    class CLIPath,MCPPath cli;
    class OrchestratorPrompt,LoadRecipeDoc handler;
    class AskOpen,Infer,FollowUp,Defaults newComponent;
    class Gate stateNode;
    class Execute phase;

Loading

Color Legend:

Color	Category	Description
Dark Blue	Terminal/CLI	Entry points and completion state
Orange	Handler	● Modified prompt construction locations
Green	New Component	● Modified conversational collection flow nodes
Teal	State	Decision: all required values inferred?
Purple	Phase	Pipeline execution (unchanged)

Closes #331

Implementation Plan

Plan file: /home/talon/projects/autoskillit-runs/conv-ingredients-20260311-214046-753062/temp/make-plan/conversational_ingredient_collection_plan_2026-03-11_120000.md

Token Usage Summary

Token Summary

fix

• input_tokens: 650
• output_tokens: 261005
• cache_creation_input_tokens: 873078
• cache_read_input_tokens: 46076601
• invocation_count: 13
• elapsed_seconds: 6260.165456347986

resolve_review

• input_tokens: 391
• output_tokens: 168303
• cache_creation_input_tokens: 449347
• cache_read_input_tokens: 21658363
• invocation_count: 7
• elapsed_seconds: 4158.092358417003

audit_impl

• input_tokens: 2771
• output_tokens: 174758
• cache_creation_input_tokens: 612009
• cache_read_input_tokens: 4594262
• invocation_count: 14
• elapsed_seconds: 5043.723946458995

open_pr

• input_tokens: 261
• output_tokens: 170926
• cache_creation_input_tokens: 528835
• cache_read_input_tokens: 8445137
• invocation_count: 10
• elapsed_seconds: 4311.458001982992

review_pr

• input_tokens: 187
• output_tokens: 246219
• cache_creation_input_tokens: 493945
• cache_read_input_tokens: 6342581
• invocation_count: 8
• elapsed_seconds: 4665.401066615992

plan

• input_tokens: 1665
• output_tokens: 187361
• cache_creation_input_tokens: 655841
• cache_read_input_tokens: 11017819
• invocation_count: 8
• elapsed_seconds: 3779.893521053007

verify

• input_tokens: 8274
• output_tokens: 151282
• cache_creation_input_tokens: 664012
• cache_read_input_tokens: 12450916
• invocation_count: 10
• elapsed_seconds: 3138.836677256011

implement

• input_tokens: 822
• output_tokens: 279442
• cache_creation_input_tokens: 928381
• cache_read_input_tokens: 62486155
• invocation_count: 11
• elapsed_seconds: 6355.765075421015

analyze_prs

• input_tokens: 15
• output_tokens: 29915
• cache_creation_input_tokens: 67472
• cache_read_input_tokens: 374939
• invocation_count: 1
• elapsed_seconds: 524.8599999569997

merge_pr

• input_tokens: 166
• output_tokens: 56815
• cache_creation_input_tokens: 314110
• cache_read_input_tokens: 4466380
• invocation_count: 9
• elapsed_seconds: 1805.746022643012

create_review_pr

• input_tokens: 27
• output_tokens: 20902
• cache_creation_input_tokens: 62646
• cache_read_input_tokens: 856008
• invocation_count: 1
• elapsed_seconds: 444.64073076299974

resolve_merge_conflicts

• input_tokens: 88
• output_tokens: 52987
• cache_creation_input_tokens: 122668
• cache_read_input_tokens: 7419558
• invocation_count: 1
• elapsed_seconds: 975.0682389580033

diagnose_ci

• input_tokens: 26
• output_tokens: 3415
• cache_creation_input_tokens: 31027
• cache_read_input_tokens: 326408
• invocation_count: 2
• elapsed_seconds: 97.75469558501209

🤖 Generated with Claude Code via AutoSkillit

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested

9 actionable findings. See inline comments.

[Trecek]

[warning] slop: [SYNC: identical block in load_recipe docstring] annotation is redundant; the sync contract is already structurally enforced by TestIngredientCollectionAlignment. Remove the annotation to avoid maintenance-burden slop.

[Trecek]

[warning] slop: [SYNC: identical block in _build_orchestrator_prompt] annotation is redundant; the sync contract is structurally enforced by TestIngredientCollectionAlignment. Remove the annotation.

[Trecek]

[warning] tests: Assertion 'infer' in prompt.lower() is too broad; the word 'infer' can appear in unrelated prompt content (e.g. 'inferred', 'inference'). Assert the full sentinel phrase 'infer as many ingredient values' instead.

[Trecek]

[warning] defense: _extract_block returns an empty string on extraction failure; outer non-empty assertions attribute the failure to a missing sentinel, obscuring a broken extractor. Raise a descriptive exception inside _extract_block rather than returning an empty sentinel value.

[Trecek]

[warning] bugs: The walk-back loop to find 'Collect ingredient values conversationally' silently leaves start at the sentinel line if the opener is not found; this produces a truncated one-line extraction that passes the alignment assertion falsely.

[Trecek]

[warning] cohesion: _extract_block is a nested function inside test_ingredient_collection_instructions_are_aligned. Move it to class scope so a future third surface does not require duplicating the extraction logic.

[Trecek]

[warning] defense: 15-line window hardcoded in _extract_block (start + 15); if the conversational block ever grows beyond 15 lines, extraction is silently truncated and the alignment assertion passes on an incomplete block. Use a named constant with a comment or make the search length-independent.

[Trecek]

[warning] bugs: If neither 'optional ingredients' nor 'default values' appears within the 15-line window, end stays at start and _extract_block returns a single line. The equality assertion then trivially passes on truncated single-line blocks, masking real divergence.

[Trecek]

[warning] bugs: line.strip() normalises indentation during block extraction. If the prompt block and docstring block ever use semantically-meaningful differing indentation (e.g., sub-clause nesting), stripping masks real divergence and the alignment assertion produces a false positive.

[Trecek]

[warning] tests: Disjunctive assertion ('free-form' in prompt.lower() or 'open-ended' in prompt.lower()) is weak: removing either phrase individually would not fail the test. Clarify whether both phrases are required (use two assertions) or if only one is canonical (assert it directly).

[Trecek]

AutoSkillit review found 9 blocking issues. See inline comments.

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested

[Trecek]

[warning] tests: _extract_block uses textwrap.dedent for comparison, but the two sources have different surrounding indentation levels. A whitespace-only change in one location will break the test without any semantic drift. Strip trailing whitespace per-line before comparing to make the comparison robust.

[Trecek]

[warning] tests: _extract_block backward search starts at sentinel_idx (inclusive) rather than sentinel_idx - 1. If the opener and sentinel ever share a line the opener would match on the sentinel line, producing a zero-length block prefix silently.

[Trecek]

[info] tests: Negative assertion scans all prompt lines for Prompt for input values using AskUserQuestion. If this phrase ever appears in a comment or example block in the prompt, the test fails spuriously. Restrict the search to numbered-list lines for precision.

[Trecek]

[info] tests: test_orchestrator_prompt_has_conversational_sentinel and test_load_recipe_docstring_has_conversational_sentinel are redundant - their failure modes are fully covered by test_ingredient_collection_instructions_are_aligned.

[Trecek]

[warning] bugs: closer_idx matches the first line of step d but the continuation line is excluded from the block slice (lines[opener_idx : closer_idx + 1]). Divergence introduced only in that continuation line would produce a false negative - the alignment test would not catch it.

[Trecek]

[warning] cohesion: _extract_block is a @staticmethod but references TestIngredientCollectionAlignment._BLOCK_MAX_LINES by fully-qualified class name. Convert to @classmethod and use cls._BLOCK_MAX_LINES for consistency.

[Trecek]

[warning] cohesion: test_orchestrator_prompt_has_conversational_sentinel and test_load_recipe_docstring_has_conversational_sentinel add no coverage beyond the alignment test. Remove them to reduce asymmetric test granularity.

[Trecek]

[info] cohesion: Duplicates the sentinel assertion already in TestIngredientCollectionAlignment.test_orchestrator_prompt_has_conversational_sentinel (test_instruction_surface.py). Split across two files without clear boundary.

[Trecek]

[info] cohesion: The conversational collection block is duplicated verbatim between _prompts.py and tools_recipe.py docstring. The alignment test guards against drift but the duplication itself is a maintenance risk. Consider extracting to a shared constant.

[Trecek]

AutoSkillit review found 5 blocking issues (warnings). See inline comments. Verdict: changes_requested.