docs: document just-in-time abstraction convention in CONTRIBUTING.md
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 45/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Stale
- Tech stack
- markdown
- Domain
- documentation
Research direction
Read PLAN.md architecture decision #2 and the relevant examples listed in the issue, then add the convention and review checklist to CONTRIBUTING.md. Link to that section from docs/ARCHITECTURE.md and update decision #2 as specified. Done means the new section is at most about 40 lines and includes the convention, checklist, and an in-repo example, with both links in place.
Written by the indexing model from the issue text.
Description
Problem Statement
PLAN.md architecture decision #2 calls for a reviewable convention: introduce an abstraction only when the second real implementation arrives. This guards ThrillhouseBot's simplicity/DRY goals under feature pressure (competitive parity with PR-Agent, Greptile cross-file context, multi-provider routing, etc.) but the rule is not yet written in CONTRIBUTING.md.
Contributors and reviewers have no shared, linkable standard when debating "should we add an interface now?" — leading to either premature abstraction or ad-hoc pushback in PR threads.
Proposed Solution
Add a short, actionable section to CONTRIBUTING.md (and cross-link from docs/ARCHITECTURE.md if appropriate) covering:
- Default: concrete implementation first; duplicate logic twice only when the second use case is real (not speculative).
- When to abstract: second distinct implementation with the same seam (e.g. second
ContextProvider, secondChatModelProvider— see #30, #55). - When not to abstract: "we might need GitLab someday" (#37), "PR-Agent has 20 tools" — ticket the feature, ship the simplest path.
- Review checklist: PR description should call out new interfaces/SPIs and justify why the second implementation exists now or why deferral is safe.
- Examples from this repo:
ReviewOrchestratordecomposition (#250 — done), §23 AI-invocation contract (ModelSelector/ContextProvider/ReviewStrategy), Qlawkus boundary discipline (citePLAN.md, not copy module count).
Pair with v0.4.0 config documentation (#50) and hosted docs (#319) so the convention is discoverable outside the repo root.
Related issues
- #50 — per-model config + config docs (same v0.4.0 docs pass)
- #319 — GitHub Pages docs site
- #314 —
quarkus-github-appspike (evaluate extension value before abstracting webhook layer) - #30 — provider SPI (future second implementation test case)
- #250 — orchestrator decomposition (positive example)
Acceptance criteria
- New
CONTRIBUTING.mdsection (≤ ~40 lines) with the convention, review checklist, and at least one in-repo example -
docs/ARCHITECTURE.mdlinks to the section (one paragraph max — no duplication) -
PLAN.mdarchitecture decision #2 updated to link the new issue (maintainer doc sync) - No code changes required — documentation only
Alternatives considered
- Issue template checkbox only — too easy to ignore; needs a visible contributor doc.
- Strict lint/rule — overkill; convention + review culture is enough for OSS.
Priority
Important for v0.4.0 docs polish — low implementation cost, high leverage as the roadmap adds competitive features (#316, #317).
Code of Conduct
- I have searched for existing issues and this is not a duplicate.
- Dominant language
- Java
- Stars
- 35
- Forks
- 7
- Avg merge
- 9h 32m
- Merged PRs (30d)
- 144
Getting set up
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from devops-thiago/ThrillhouseBot
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
devops-thiago/ThrillhouseBot#1093 ·
Maintainers usually reply within 1 day
-
documentation enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
devops-thiago/ThrillhouseBot#321 ·
Maintainers usually reply within 1 day
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
devops-thiago/ThrillhouseBot#46 ·
Maintainers usually reply within 1 day
-
fix(review): preserve tilde-fenced code during path screeningPossibly taken @devops-thiago claimed this today. Openbug java
Difficulty 4/5 1-2 days Newbie friendliness 35/100
devops-thiago/ThrillhouseBot#1111 · 1 comment ·
Maintainers usually reply within 1 day
-
fix(review): exclude TAP TODO and SKIP results from CI failuresPossibly taken @devops-thiago claimed this today. Openbug java
Difficulty 3/5 1-2 days Newbie friendliness 35/100
devops-thiago/ThrillhouseBot#1110 · 1 comment ·
Maintainers usually reply within 1 day
All issues in devops-thiago/ThrillhouseBot
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
objectionary/lints#1556 ·
Maintainers usually reply within 3 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
wildfly/wildfly-launcher#99 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
apache/rocketmq#11427 · 2 comments ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
A failed JNA download is reported as a corrupt zip, because `curl` in `Makefile` lacks `--fail`Open
Difficulty 1/5 Under an hour Newbie friendliness 88/100
objectionary/phino#1884 · 1 comment ·
Maintainers usually reply within 1 day