Skip to content

feat: Include a suggested remediation in violation output #73

Description

@Tgenz1213

Problem

AnalysisResult (internal/llm/llm.go:17-21) and ChatPrompt (llm.go:75-99) only ask the LLM for violation, reasoning, and quoted_code. A violation report tells you what is wrong and why (engine.go:235-236: [VIOLATION] ... / Reasoning: ...) but not what to do about it. For an architectural violation (e.g. "this file is JavaScript but the ADR mandates Go"), the fix is rarely a one-line patch, but even a short remediation pointer ("move this logic into a Go service and call it from here" / "this needs to be rewritten in Go, not automatically portable") saves the reader from re-deriving the ADR's implication themselves.

Acceptance Criteria

  • AnalysisResult gains a Suggestion string field, populated only when violation is true (empty/omitted otherwise).
  • Suggestion text is a short remediation pointer, not a claimed code patch/diff — it must be clearly framed (in the prompt and in output) as an LLM-generated pointer, not a guaranteed or verified fix, since ArchGuard has no ability to validate that following it actually resolves the violation.
  • CLI output (engine.go:235-239) prints the suggestion under the existing Reasoning:/Code: lines when present, e.g. Suggestion: ....
  • --format json (if feat: Add machine-readable (--format json) output to archguard check #70 lands first) includes the field; if it lands first, this ticket should be sequenced after it so the schema is defined once.
  • Existing violation-detection behavior (the violation/reasoning/quoted_code judgment itself) is unchanged in accuracy — covered by not modifying DefaultSystemPrompt's literal-mindedness rules (llm.go:66-73), only adding the new output field.
  • Tests cover the new field via llm.MockProvider and confirm it's empty when violation is false.

Open design question

Whether to ask for suggestion in the same prompt/call as the violation judgment (cheaper — one round trip) or via a second call made only when res.Violation is already true (preserves the existing prompt's narrowly-scoped, deliberately literal-minded judgment task untouched, avoiding any risk that adding "and suggest a fix" instructions subtly biases the model toward finding violations to have something to suggest). Given DefaultSystemPrompt's explicit "FALSE BY DEFAULT" design intent, the second-call approach is the safer default and should be the starting point unless benchmarking shows the combined prompt doesn't measurably change violation-detection behavior.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions