What Convention/Pattern Was Missed?
When writing unit tests, I used both the test_ prefix AND the #[Test] attribute together on test methods. The project convention is to use ONLY the test_ prefix without the #[Test] attribute, but this wasn't explicitly stated in the testing conventions.
What I Saw When Invoked
When the backend-engineer role was activated, I was directed to read .claude/rules/backend/testing-conventions.md. The file showed examples using the test_ prefix method naming pattern and mentioned that the #[Test] attribute "is acceptable" in modern PHPUnit. The backend-reviewer agent also approved my code saying the #[Test] usage "is acceptable and recommended in modern PHPUnit." This created ambiguity about what the project actually wants.
Task Context (Generic)
Writing comprehensive unit tests for a Data class, following project testing conventions for test structure, naming, and assertions.
Why Wasn't It Clear?
The testing conventions file (.claude/rules/backend/testing-conventions.md) shows examples with the test_ prefix but doesn't explicitly prohibit using the #[Test] attribute. It even states both patterns "are acceptable" which suggests they're interchangeable, when in fact the project has a clear preference. The backend-reviewer agent's approval further reinforced that using both together was fine, when it actually violated the project's convention.
Which Documentation Files Need Updates
project-roles/skills/php-test-writer/SKILL.md.claude/rules/backend/testing-conventions.md (user's project file, but referenced by plugin)project-roles/agents/backend-reviewer.md
Proposed Improvement
File: project-roles/skills/php-test-writer/SKILL.md
Change:
```markdown
Test Method Naming - CRITICAL Pattern
ALWAYS use the `test_` prefix. DO NOT use the `#[Test]` attribute.
```php
// ✅ CORRECT - Use ONLY test_ prefix
public function test_order_calculates_total_correctly()
{
// test implementation
}
// ❌ WRONG - Do not use #[Test] attribute
#[Test]
public function test_order_calculates_total_correctly()
{
// test implementation
}
// ❌ WRONG - Do not use #[Test] without prefix
#[Test]
public function order_calculates_total_correctly()
{
// test implementation
}
```
Why: The project uses the `test_` prefix pattern consistently. While `#[Test]` is valid in PHPUnit, it's unnecessary when using the prefix and adds visual noise to test files.
```
Why: This creates an explicit visual checkpoint showing exactly what's wrong. By leading with the negative examples and using strong language ("DO NOT"), it makes the convention impossible to miss. Adding this to the php-test-writer skill ensures it's loaded before writing any tests.
Additional Context
The backend-reviewer agent also needs updating to flag `#[Test]` usage as a convention violation. Currently it approved code using this pattern, which reinforces the wrong behavior. Consider adding a checklist item: "❌ Using `#[Test]` attribute? → Should use ONLY `test_` prefix"
Component: Skill - php-test-writer (and backend-reviewer agent)
Plugin: project-roles
What Convention/Pattern Was Missed?
When writing unit tests, I used both the
test_prefix AND the#[Test]attribute together on test methods. The project convention is to use ONLY thetest_prefix without the#[Test]attribute, but this wasn't explicitly stated in the testing conventions.What I Saw When Invoked
When the
backend-engineerrole was activated, I was directed to read.claude/rules/backend/testing-conventions.md. The file showed examples using thetest_prefix method naming pattern and mentioned that the#[Test]attribute "is acceptable" in modern PHPUnit. The backend-reviewer agent also approved my code saying the#[Test]usage "is acceptable and recommended in modern PHPUnit." This created ambiguity about what the project actually wants.Task Context (Generic)
Writing comprehensive unit tests for a Data class, following project testing conventions for test structure, naming, and assertions.
Why Wasn't It Clear?
The testing conventions file (
.claude/rules/backend/testing-conventions.md) shows examples with thetest_prefix but doesn't explicitly prohibit using the#[Test]attribute. It even states both patterns "are acceptable" which suggests they're interchangeable, when in fact the project has a clear preference. The backend-reviewer agent's approval further reinforced that using both together was fine, when it actually violated the project's convention.Which Documentation Files Need Updates
project-roles/skills/php-test-writer/SKILL.md.claude/rules/backend/testing-conventions.md(user's project file, but referenced by plugin)project-roles/agents/backend-reviewer.mdProposed Improvement
File:
project-roles/skills/php-test-writer/SKILL.mdChange:
```markdown
Test Method Naming - CRITICAL Pattern
ALWAYS use the `test_` prefix. DO NOT use the `#[Test]` attribute.
```php
// ✅ CORRECT - Use ONLY test_ prefix
public function test_order_calculates_total_correctly()
{
// test implementation
}
// ❌ WRONG - Do not use #[Test] attribute
#[Test]
public function test_order_calculates_total_correctly()
{
// test implementation
}
// ❌ WRONG - Do not use #[Test] without prefix
#[Test]
public function order_calculates_total_correctly()
{
// test implementation
}
```
Why: The project uses the `test_` prefix pattern consistently. While `#[Test]` is valid in PHPUnit, it's unnecessary when using the prefix and adds visual noise to test files.
```
Why: This creates an explicit visual checkpoint showing exactly what's wrong. By leading with the negative examples and using strong language ("DO NOT"), it makes the convention impossible to miss. Adding this to the php-test-writer skill ensures it's loaded before writing any tests.
Additional Context
The backend-reviewer agent also needs updating to flag `#[Test]` usage as a convention violation. Currently it approved code using this pattern, which reinforces the wrong behavior. Consider adding a checklist item: "❌ Using `#[Test]` attribute? → Should use ONLY `test_` prefix"
Component: Skill - php-test-writer (and backend-reviewer agent)
Plugin: project-roles