Add conditional rule logic for first-time contributors

[dkargatzis]

Summary

Add conditional rule logic to Watchflow to apply stricter checks for first-time contributors. First-time contributors (users with no prior merged PRs) often need additional scrutiny, but applying the same rules to all contributors can create friction for newcomers.

Motivation

• First-time contributors may not be familiar with project conventions
• Additional validation (tests, docs, changelog) helps maintain quality
• Stricter rules for newcomers reduces risk of unexpected issues
• However, over-restricting can discourage contributions

Proposed Solution

Add conditional logic to the rule engine that allows rules to be applied only when certain conditions are met. For example:

Use Cases

1. First-time contributor checks

   rules:
     - name: Require Changelog
       condition: contributor.is_first_time
     - name: Require Tests
       condition: contributor.pr_count == 0
     - name: Require Description
       condition: contributor.pr_count < 3

2. File-pattern based rules

   • Only require tests for sensitive paths (e.g., src/auth/) for external contributors

3. Team-specific rules

   • Only apply certain checks for external collaborators
   • Relaxed rules for core team members

Proposed Implementation

Add a condition field to rules in rules.yaml:

rules:
  - name: Require Changelog
    condition: contributor.pr_count == 0 or files.match("src/auth/**")
    parameters:
      changelog_required: true

Available Conditions

• contributor.pr_count — Number of merged PRs by the contributor
• contributor.is_first_time — Shorthand for contributor.pr_count == 0
• contributor.trusted — User has merged PRs or is a CODEOWNER
• files.match(pattern) — Changed files match glob pattern
• risk.level — PR risk assessment level

Technical Approach

1. Add a contributor context to the evaluation pipeline
2. Parse condition in rules.yaml as an expression
3. Evaluate condition before applying the rule
4. If condition is false, skip the rule (log at debug level)

Benefits

• Flexibility — Tailor rules to contributor experience level
• Lower barrier — First-time contributors know exactly what's expected
• Reduced friction — Core team members don't get blocked by basic requirements

References

• GitHub's first-time contributor indicator: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-working-with-webhooks/pulling-external-changes
• Related: Watchflow's /reviewers and /risk commands that already assess contributor history

[codesensei-tushar]

Hey @dkargatzis, I'd love to take this on.

This is a substantial feature, so I'd like to break it into incremental PRs rather than one large delivery:

PR 1 (v1) — Structured when: block with named predicates

when:
  contributor: first_time   # or trusted, or pr_count_below: 3
  files_match: "src/auth/**"

No expression parser — just named predicates that cover the issue's core use cases.

Deliverables:

• ContributorContext fetched in the enricher via GET /search/issues?q=is:pr+author:X+is:merged+repo:owner/repo (cached per evaluation)
• when: block on the rule model + loader
• Rule engine skips the rule when when evaluates false
• Unit tests for each predicate and the skip path

PR 2 — Expression parser

• Replace the structured when: block with a proper expression evaluator supporting and / or / == / < / >
• Security-safe (no arbitrary eval), probably a small recursive descent parser
• Enables: condition: contributor.pr_count < 3 and files.match("src/auth/**")

PR 3 — Extended predicates

• risk.level condition tied to existing /risk command
• contributor.role for team-specific rules (CODEOWNER, collaborator, external)
• Composite use cases from the issue (team-specific rules, file-pattern + contributor combos)

---

Two questions before I start:

1. Does the structured when: approach work for v1, or do you want the expression parser from the start?
2. Is the search API acceptable for PR count, or would you prefer a persistent store?

[dkargatzis]

Hey @codesensei-tushar, great breakdown! Love the incremental approach.

Answers to your questions:

1. Structured when: for v1 — keeps it simple and covers the main use cases. We can add expression parser in v2 once the foundation is solid.

2. Search API for v1 — acceptable for the MVP. We can add a persistent store later if the search API becomes a bottleneck. Persistence will be a Warestack Enterprise ready feature (Redis, Postgres, Pgvector are already part of our core stack).

One suggestion for PR 1:

Add a reason field to the skip log so it's clear why a rule was skipped:

DEBUG Rule "Require Changelog" skipped: contributor is not first-time

Approved to start. Let me know when you open the first PR.

Btw, are you open to a quick sync to discuss the feature in more detail? Always good to align early.

Side note on persistence: We're keeping Watchflow's self-hosted setup minimal (no mandatory persistence layer) to keep it easy to deploy. If you have ideas on how to bundle everything together for users who want persistence, I'd be happy to discuss — could be a good architecture conversation.

[codesensei-tushar]

Thanks @dkargatzis — all clear. PR 1 will open it soon with the reason field included.
As you said, we can layer in persistence if the Search API becomes a bottleneck the codebase already has a TTL cache pattern that'd be a natural first step.

Would love to sync — happy to work around your schedule. The persistence architecture discussion would be a great learning experience for me, especially around how the self-hosted and enterprise sides connect. Looking forward to it.

[dkargatzis]

@codesensei-tushar book a time slot that works best for you - looking forward to discussing further, shaping the direction of Watchflow, and potentially getting you involved with Warestack!

Here is my Calendly.