feat(planning): compile trigger input into a structured run brief before agent execution

[rtzll]

Related: #119

Summary

Rascal currently accepts manual task text and GitHub-triggered feedback, then passes that input into run artifacts without a first-class planning layer that normalizes intent.

This issue adds a deterministic run-brief compiler that turns issue bodies, PR comments, review comments, and manual prompts into a structured execution brief the backend can follow more reliably.

Outcome

Every run begins with a normalized run-brief artifact that captures the objective, constraints, acceptance criteria, relevant files, validation expectations, and follow-up context in a backend-neutral format.

Goals

• Improve first-pass run quality by clarifying ambiguous trigger input.
• Separate raw trigger content from the normalized brief the agent should execute against.
• Make planning decisions inspectable in run artifacts.
• Keep the system deterministic and compatible with both supported backends.
• Compose cleanly with the context-pack work in feat(context): add scoped repo knowledge packs and rule ingestion for runs #119.

Non-goals

• Letting the model freely rewrite the user’s intent.
• Building a generic ticket-planning product.
• Implementing semantic search or repo-wide retrieval in this issue.
• Solving multi-agent orchestration here.

Scope

Implement V1 run-brief compilation with the following pieces.

1. Input normalization

• Support the current Rascal trigger classes, including:
  • manual CLI/API task text
  • issue label / issue edit flows
  • PR comment feedback
  • PR review feedback
  • PR review comment feedback
• Normalize raw inputs into a shared intermediate model.
• Preserve original source text in artifacts for traceability.

2. Run brief schema

• Add explicit artifacts such as:
  • run-brief.json
  • run-brief.md
• The brief should capture at least:
  • primary objective
  • background/context summary
  • constraints and instructions
  • acceptance criteria
  • likely target files or paths when directly inferable
  • requested validation or follow-up behavior
  • unresolved ambiguities or assumptions
• Keep the schema compact and inspectable.

3. Deterministic extraction rules

• Add a deterministic extraction pass that can identify common structure from GitHub input, such as:
  • checkbox lists
  • fenced code blocks
  • quoted prior feedback
  • inline file/path references
  • explicit "do not" constraints
• Strip noise that should not dominate the brief, while preserving it in source artifacts.
• Avoid hidden prompt magic in V1.

4. Ambiguity handling

• If the trigger input is too vague, record that explicitly in the brief.
• Add conservative fallback behavior such as:
  • continue with a minimal brief and explicit assumptions
  • optionally fail fast for configuration-controlled trigger classes later
• The brief should never pretend the request was clearer than it was.

5. Dry-run visibility

• Add a CLI/debug path to inspect the compiled brief without running the backend, for example:
  • rascal run --dry-run-brief
  • rascal brief issue OWNER/REPO#123
• The output should show both the normalized brief and the raw source summary.

6. Prompt assembly integration

• Thread the compiled brief into the existing run artifact generation and prompt assembly flow.
• Keep backend-specific prompt formatting separate from the brief compiler itself.
• The backend should receive the normalized brief as the primary execution contract.

Suggested implementation approach

1. Add a small internal planning package.

• Separate source loading, normalization, extraction, and rendering.
• Model a stable RunBrief type with explicit provenance.

2. Keep extraction heuristics shallow and deterministic.

• Prefer regex/tokenization/markdown-structure parsing over opaque model-based rewriting.
• If later model-assisted planning is added, it should layer on top of this deterministic base.

3. Preserve provenance.

• Each field in the brief should be traceable to a raw source or a deterministic derivation.
• Ambiguous derived fields should carry an explanation.

4. Integrate cleanly with feat(context): add scoped repo knowledge packs and rule ingestion for runs #119.

• The run brief describes what needs to be done.
• The context pack describes what repo guidance should accompany it.
• Do not collapse the two concerns into one artifact.

5. Make failures explicit.

• If source loading from GitHub fails, surface that as a planning error with a clear reason.
• Avoid silently compiling partial briefs that look authoritative.

Acceptance criteria

• Rascal can compile raw trigger input into a normalized run brief for all current trigger classes.
• The brief is persisted as explicit JSON and Markdown artifacts in the run directory.
• The compiled brief preserves provenance and ambiguity notes.
• Operators can inspect the brief without starting a backend run.
• Backend prompt assembly uses the run brief as a first-class input.
• Tests cover manual tasks, issue-driven runs, PR feedback runs, ambiguity handling, and artifact rendering.

Suggested test plan

• Unit tests for markdown extraction and path/reference detection.
• Unit tests for trigger-specific brief compilation.
• Integration tests for issue/comment/review payloads producing stable run-brief.json output.
• Regression tests for noisy GitHub comments that include quoted text or code fences.
• CLI tests for dry-run brief inspection.

Implementation notes

• The brief compiler should clarify intent, not invent it.
• Keep the initial schema small enough that humans will actually read it during debugging.
• A dependable deterministic planner is more valuable here than a clever but unstable one.

[rtzll]

Rascal started run run_7930e4e7314a9eac for this issue.

Run Settings

• Requested by: rtzll

• Trigger: issue_label

• Backend: goose

• Runner commit: 4acda06d500d839952f91318044ef9a6c6dcb888

• Branches: main -> rascal/rtzll/rascal-162-7930e4e731

• Session mode: all

• Resume: true

• Debug: true

• Queue delay: 27m 37s

• Task: feat(planning): compile trigger input into a structured run brief before agent execution Related: feat(context): add scoped repo knowledge packs and rule ingestion for runs #119 ## Summary Rascal currently accepts manual task text and GitHub-triggered feedback, then passes that input into run artifacts without a first-class planning layer that normal...

• Context: Triggered by label 'rascal' on issue feat(planning): compile trigger input into a structured run brief before agent execution #162

[rtzll]

Rascal started run run_8eb3f7257e3d893c for this issue.

Run Settings

• Requested by: rtzll

• Trigger: issue_label

• Agent Runtime: goose

• Runner commit: f57a5f063c7f38ffe8e901bfeab6af08dba04b1a

• Branches: main -> rascal/rtzll/rascal-162-8eb3f7257e

• Session mode: all

• Resume: true

• Debug: true

• Queue delay: 35m 7s

• Instruction: feat(planning): compile trigger input into a structured run brief before agent execution Related: feat(context): add scoped repo knowledge packs and rule ingestion for runs #119 ## Summary Rascal currently accepts manual task text and GitHub-triggered feedback, then passes that input into run artifacts without a first-class planning layer that normal...

• Context: Triggered by label 'rascal' on issue feat(planning): compile trigger input into a structured run brief before agent execution #162