feat(aidd-dev): report rule influence on development decisions

Open
#796 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active

Research direction

Start by reading 01-plan/02-explore, 01-plan/assets/plan-template.md, 02-implement/SKILL.md, 05-review/03-review-relevancy.md, and the cited architecture section. Define and implement a backward-compatible contract for material rule influence in the existing Decisions table, with explicit reliability and no-influence behavior, then verify the acceptance criteria across planning, implementation, and review.

Written by the indexing model from the issue text.

Description

Problem

aidd-dev:01-plan identifies project rules that apply to a planned file projection, and aidd-dev:05-review can cite a rule when it finds a violation. Neither provides an observable trace from a rule that materially influenced a development decision to the affected artifact.

When generated code is undesirable, a maintainer cannot reliably distinguish a bad implementation decision from an ambiguous, conflicting, or unsuitable project rule. Listing every rule available in context would not answer that question.

Scope
  • Report a rule influence trace only when a project rule materially influences a development decision by selecting it over a meaningful alternative.
  • Record the trace in the existing plan ## Decisions table rather than creating a separate trace store.
  • For each reported entry, identify the Decision, the concrete rule-driven Why, and the Rule Source to verify.
  • Reuse the plan phase projection for affected files instead of repeating those files in the decision table.
  • Make the output explicit about its reliability: captured or observed influence where the workflow can support it; otherwise model-reported influence, never guaranteed provenance or hidden reasoning.
  • Applicable but non-decisive Rules produce no decision-trace entry.
  • Implementation and review may read an existing decision trace, but must never infer Rule influence retrospectively.
  • Preserve a useful no-influence result when no project-specific rule materially affects the change.
  • Keep generated application source free of provenance-only comments.
Acceptance criteria
  • A development workflow can report a project Rule that materially influenced a decision.
  • The existing plan ## Decisions table is used for rule-influence entries; no separate trace store is introduced.
  • Every reported entry records Decision, Why, and Source.
  • An entry is created only when a Rule materially selects a decision over a meaningful alternative.
  • Affected files are not duplicated in the decision table when they are already present in the plan phase projection.
  • The report does not mechanically list every Rule loaded or available in context.
  • An unrelated or merely applicable Rule is not reported as influential.
  • The output states whether each trace is captured, observed, or model-reported; it does not claim to prove internal LLM reasoning.
  • No application source file is modified solely to persist Rule provenance.
  • Implementation and review do not infer Rule influence after the decision has been made.
  • A workflow with no materially influential project Rule remains valid and reports no invented influence.
  • Existing Plan, Implement, and Review behavior remains backward compatible unless the accepted design deliberately changes its contract.
Prior art in this repo

01-plan/02-explore already selects applicable project rules and justifies them. This is the initial rule-selection seam, but applicability is not material influence.

01-plan/assets/plan-template.md already provides the concise ## Decisions table; the accepted design must carry the Rule Source alongside Decision and Why.

02-implement owns code transformation against an existing plan.

05-review/03-review-relevancy discovers declared rules and can cite a violated rule, but does not report influences that led to compliant decisions.

docs/ARCHITECTURE.md assigns code transformation to aidd-dev; therefore this concern belongs there rather than in aidd-context.

Related, complementary issues:

  • #791 prevents overlap or conflicts while creating a new Rule.
  • #792 audits an existing Rule corpus for conflicts, duplication, and drift.
  • #793 audits context architecture and ownership across artifact types.

I checked open and closed issues, merged/open PRs, Discussions, and the current main contracts. No proposal covers Rule -> materially influenced decision -> artifact. PR #795 concerns session telemetry, not rule-to-decision traceability.

Out of scope
  • Exposing chain-of-thought or claiming proof of internal LLM reasoning.
  • Treating every loaded Rule as applied.
  • Adding provenance comments to application source.
  • Adding a separate trace store or inferring influence after the decision has been made.
  • Automatically rewriting, deleting, or resolving conflicts between Rules.
  • Replacing #791, #792, #793, or redesigning the whole context architecture.
  • Enterprise-specific behavior.
Dominant language
TypeScript
Stars
481
Forks
45
Avg merge
17h 40m
Merged PRs (30d)
106

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ai-driven-dev/framework

All issues in ai-driven-dev/framework

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.