feat(aidd-context): check existing rules for overlap or conflicts during rule generation

Open
#791 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
64/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Domain
tooling

Research direction

Start with plugins/aidd-context/skills/05-rule-generate/SKILL.md, then read 01-capture-rule.md, 02-write-rule.md, 03-validate.md, and references/tool-paths.md to understand the current flow and canonical rule surfaces. Add the pre-write assessment and approval gate without changing existing write or validation contracts; done means covered, overlap, conflict, needs review, and new cases identify relevant files and require an explicit user decision before writing.

Written by the indexing model from the issue text.

Description

Problem

aidd-context:05-rule-generate captures a rule intent, writes the rule for the selected target tools, then validates the generated files against the rule-authoring and tool-path contracts.

The workflow does not currently make comparison with the project's existing rules an explicit validation step before writing the candidate rule. As the rule corpus grows, a generated rule can duplicate an existing instruction, partially overlap it, contradict it, or introduce a different scope or priority for an already-covered concern.

This matters because repository-level AGENTS.md already requires checking whether an existing instruction, finding, or rule covers or contradicts a new one, then merging, removing, or clarifying it when necessary. The principle exists, but is not an explicit 05-rule-generate contract.

Scope
  • Discover existing project rules relevant to the candidate before writing it through the canonical 05-rule-generate/references/tool-paths.md reference; do not add a tool-specific path list to this assessment.
  • Assess the candidate policy, intent, and scope rather than comparing only its topic or title.
  • Exclude expected cross-tool renderings of the same canonical policy from duplicate findings and filter rules whose scopes are disjoint from the candidate.
  • Classify the candidate as new, covered, overlap, conflict, or needs review.
  • Surface the existing rule files involved in every non-new result.
  • Add an explicit pre-write assessment step between capture and write: 01 capture → 02 assess existing rules → 03 write → 04 validate.
  • Stop before writing until the user has explicitly chosen how to handle the assessment result.
  • Offer resolutions such as keeping the existing rule, merging, updating, clarifying scope or priority, creating anyway, or cancelling.
  • Require explicit user approval before modifying an existing rule.
  • Keep this as a guard inside 05-rule-generate, not a new skill.
  • Preserve the existing write and validation contracts.
Acceptance criteria
  • The workflow performs an explicit assessment step after capture and before writing.
  • Rule sources are discovered through the canonical 05-rule-generate/references/tool-paths.md reference.
  • Given a candidate whose policy is already expressed by an applicable existing rule, rule-generate identifies that rule before creating a duplicate.
  • Given compatible but partially redundant instructions, the workflow reports overlap and identifies both rule sources.
  • Given Always use pytest for unit tests and Use unittest for all unit tests, the workflow reports conflict before writing the candidate.
  • Rules with disjoint scopes are excluded from overlap and conflict findings.
  • Expected cross-tool renderings of the same canonical policy are not reported as duplicates.
  • Each candidate is classified as new, covered, overlap, conflict, or needs review.
  • Every non-new result identifies the involved rule files.
  • The user makes an explicit decision before the candidate is written.
  • The user can explicitly choose how to resolve an overlap or conflict.
  • Existing rule files are never modified without explicit user approval.
  • A candidate classified as new continues through the existing write and validation workflow.
  • Existing structural, path, frontmatter, and per-tool validation behavior remains unchanged.
Prior art in this repo
  • AGENTS.md#L27 already requires checking whether an existing instruction, finding, or rule covers or contradicts a new one before adding it.
  • 05-rule-generate/SKILL.md#L8-L19 defines the current three-action flow: capture, write, validate; this issue adds the pre-write assessment step.
  • tool-paths.md is the canonical source for supported rule surfaces and target paths.
  • 01-capture-rule.md#L3-L28 captures topic, category, slug, scope, and write mode; it does not define semantic comparison with the existing rule corpus.
  • 02-write-rule.md#L3-L26 builds and renders the rule for supported tools.
  • 03-validate.md#L3-L22 validates written files against the authoring and tool-path contracts, but does not define a cross-rule consistency check.

I searched the repository's open and closed issues and pull requests for an equivalent semantic duplicate, overlap, or conflict proposal. Issue #788 concerns current Kilo/OpenCode output paths, not semantic consistency, so it is not a duplicate.

Out of scope
  • Auditing the complete existing rule corpus independently of generating a new rule; that is #792.
  • Automatically rewriting, merging, or deleting existing rules without user approval.
  • Defining a universal precedence system between all AI tools.
  • Changing existing rule file formats or target-tool mappings.
Dominant language
TypeScript
Stars
481
Forks
45
Avg merge
14h 36m
Merged PRs (30d)
110

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.