fix: add additional directory paths to ADR assessor

[jeremyeder]

Summary

• Add specs/, docs/specs/, docs/architecture/, and docs/design/ to the ADR assessor's checked paths
• Update the failure evidence message to list all 8 checked directories

Projects using these common conventions for architectural decision documentation were getting false failures on the architecture_decisions check.

Closes #414

Test plan

• All existing tests pass (53 passed, 4 skipped, 1 unrelated worktree-name assertion failure)
• Pre-commit hooks pass (black, ruff, isort, conventional commit)

🤖 Generated with Claude Code

[coderabbitai]

Warning

.coderabbit.yaml has a parsing error

The CodeRabbit configuration file in this repository has a parsing error and default settings were used instead. Please fix the error(s) in the configuration file. You can initialize chat with CodeRabbit to get help with the configuration file.

💥 Parsing errors (1)

Validation error: String must contain at most 250 character(s) at "tone_instructions"

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Walkthrough

Two minor updates to assessors in a single documentation module: reformatted README remediation examples and expanded ADR directory search to include specs, docs/specs, docs/architecture, and docs/design as alternative paths.

Changes

Documentation Assessors

Layer / File(s)	Summary
README remediation example formatting src/agentready/assessors/documentation.py (lines 482–507)	READMEAssessor._create_remediation() reformats the first example in the examples list from inline to a properly separated multiline triple-quoted string for improved readability.
ADR directory path expansion src/agentready/assessors/documentation.py (lines 560–580)	ArchitectureDecisionsAssessor adds four candidate ADR directory paths (specs/, docs/specs/, docs/architecture/, docs/design/) to the search. The "No ADR directory found" error message is updated to reflect the expanded set of checked locations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding additional directory paths to the ADR assessor.
Description check	✅ Passed	The description directly addresses the changeset by explaining what paths were added, why they were needed, and references the related issue.
Linked Issues check	✅ Passed	The changes fully address issue #414 requirements: adds the four proposed directory paths (specs/, docs/specs/, docs/architecture/, docs/design/) and updates the failure message to list all checked directories.
Out of Scope Changes check	✅ Passed	All changes are directly related to expanding ADR directory paths and updating the corresponding error message, with no unrelated modifications present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/agentready/assessors/documentation.py (1)

555-563: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Generic ADR paths can cause false-positive passes.

At Line 560-563, broad directories like specs/ and docs/specs/ may contain non-ADR markdown docs; with current scoring, directory existence + file count can pass even when ADR quality is absent.

Suggested guard to reduce false positives in generic directories

-        adr_paths = [
-            repository.path / "docs" / "adr",
-            repository.path / ".adr",
-            repository.path / "adr",
-            repository.path / "docs" / "decisions",
-            repository.path / "specs",
-            repository.path / "docs" / "specs",
-            repository.path / "docs" / "architecture",
-            repository.path / "docs" / "design",
-        ]
+        adr_candidates = [
+            (repository.path / "docs" / "adr", False),
+            (repository.path / ".adr", False),
+            (repository.path / "adr", False),
+            (repository.path / "docs" / "decisions", False),
+            (repository.path / "specs", True),
+            (repository.path / "docs" / "specs", True),
+            (repository.path / "docs" / "architecture", True),
+            (repository.path / "docs" / "design", True),
+        ]

         adr_dir = None
-        for path in adr_paths:
+        selected_is_generic = False
+        for path, is_generic in adr_candidates:
             if path.exists() and path.is_dir():
                 adr_dir = path
+                selected_is_generic = is_generic
                 break

-            adr_files = list(adr_dir.glob("*.md"))
+            adr_files = list(adr_dir.glob("*.md"))
+            if selected_is_generic:
+                adr_files = [
+                    f for f in adr_files
+                    if re.match(r"^(\d{4}-|ADR-\d{3}-|adr-\d{3}-)", f.name)
+                ]

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/agentready/assessors/documentation.py` around lines 555 - 563, The ADR
path list (adr_paths) is too generic and causes false positives by counting
non-ADR files under directories like "specs" or "docs/specs"; update the ADR
detection logic (where adr_paths is used in the ADR assessor function) to not
just check directory existence/file count but to inspect candidate files for
ADR-specific signals—e.g., filename patterns (contains "adr" or "decision" or
matches "*-adr*.md"), ADR frontmatter keys (e.g., "status", "deciders"), or a
top-level heading like "Architectural Decision"—and only count files that match
those heuristics when computing ADR score. Ensure the code references the
adr_paths list and the function/class that calculates ADR score so the new
filtering is applied before incrementing counts.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/agentready/assessors/documentation.py`:
- Around line 555-563: The ADR path list (adr_paths) is too generic and causes
false positives by counting non-ADR files under directories like "specs" or
"docs/specs"; update the ADR detection logic (where adr_paths is used in the ADR
assessor function) to not just check directory existence/file count but to
inspect candidate files for ADR-specific signals—e.g., filename patterns
(contains "adr" or "decision" or matches "*-adr*.md"), ADR frontmatter keys
(e.g., "status", "deciders"), or a top-level heading like "Architectural
Decision"—and only count files that match those heuristics when computing ADR
score. Ensure the code references the adr_paths list and the function/class that
calculates ADR score so the new filtering is applied before incrementing counts.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: c2042a18-b9b1-4a86-8a73-363204fbe118

📥 Commits

Reviewing files that changed from the base of the PR and between 9ada97c and f800477.

📒 Files selected for processing (1)

• src/agentready/assessors/documentation.py

[kami619]

@jeremyeder : https://github.com/ambient-code/agentready/actions/runs/25739234886/job/75584634017?pr=416#step:5:17 black check's failing.

[jeremyeder]

@jeremyeder : https://github.com/ambient-code/agentready/actions/runs/25739234886/job/75584634017?pr=416#step:5:17 black check's failing.

fixed in pr417

[github-actions]

🎉 This PR is included in version 2.35.3 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀