Coding
GOLD STANDARD DEVELOPMENT RULE — DOCUMENTATION + TESTING + COMPLETION GATE
by rajesh · updated 9/19/2026
Prompt
# GOLD STANDARD DEVELOPMENT RULE — DOCUMENTATION + TESTING + COMPLETION GATE
This is a **permanent and mandatory development rule for this repository**.
It applies to **every coding request**, including:
* New features
* New functionality
* Feature enhancements
* Bug fixes
* UI changes
* UX changes
* API changes
* Database changes
* Authentication/authorization changes
* Refactoring that changes behavior
* Configuration changes affecting application behavior
* Integration changes
* Background jobs
* Scheduled tasks
* Business logic
* Validation logic
* Performance-related functional changes
A coding task MUST NOT be considered complete merely because the implementation compiles, builds, or appears to work.
---
# 1. GOLDEN RULE
For **EVERY feature or functionality you create, modify, fix, or extend**, you MUST:
1. Implement the functionality.
2. Update its dedicated feature/functionality documentation.
3. Create or update relevant **Unit Tests**.
4. Create or update relevant **Functional / Integration Tests**.
5. Create or update relevant **UI/UX / End-to-End Tests** when the functionality has any user-facing impact.
6. Execute the applicable tests.
7. Fix failures caused by the change.
8. Verify documentation matches the final implementation.
9. Only then report the feature as completed.
Therefore:
> **CODE + DOCUMENTATION + UNIT TESTS + FUNCTIONAL TESTS + UI/UX TESTS + VERIFICATION = DONE**
Code alone is **NOT DONE**.
---
# 2. FEATURE DOCUMENTATION IS MANDATORY
Every feature/functionality MUST have a dedicated Markdown documentation file.
Preferred structure:
```text
docs/
features/
authentication.md
attendance.md
leave-management.md
employee-management.md
notifications.md
reports.md
billing.md
```
If a suitable feature document already exists:
> UPDATE IT.
If no suitable document exists:
> CREATE IT.
Do NOT create duplicate documentation files for the same feature unnecessarily.
Each feature Markdown file should contain, where applicable:
```text
# Feature Name
## Overview
## Purpose
## User Stories
## Functional Requirements
## Business Rules
## User Roles / Permissions
## User Flow
## UI/UX Behaviour
## API / Backend Behaviour
## Data Model / Database Changes
## Validation Rules
## Error Handling
## Edge Cases
## Security Considerations
## Dependencies
## Configuration
## Unit Tests
## Functional / Integration Tests
## UI/UX / E2E Tests
## Known Limitations
## Change History
```
Documentation MUST describe the **actual final implementation**, not the originally planned implementation.
---
# 3. DOCUMENTATION MUST BE UPDATED DURING DEVELOPMENT
Do not treat documentation as optional cleanup work.
Whenever implementation changes:
* Business rules
* UI behaviour
* API behaviour
* Validation
* Permissions
* Database structure
* Workflow
* Error handling
* Configuration
* Integrations
* User journeys
the corresponding feature Markdown file MUST also be updated.
Documentation and implementation must remain synchronized.
---
# 4. UNIT TESTS ARE MANDATORY
Every feature/functionality must have appropriate Unit Tests.
Unit tests should cover applicable areas such as:
* Business logic
* Utility functions
* Services
* Validation
* Transformation logic
* Permission logic
* State transitions
* Calculations
* Error handling
* Boundary conditions
* Positive scenarios
* Negative scenarios
Do NOT write meaningless tests purely to increase coverage.
Tests must verify actual expected behaviour.
Where appropriate, test:
```text
Happy Path
Negative Path
Boundary Conditions
Invalid Input
Missing Input
Unexpected Input
Permission Failure
Error Conditions
State Changes
Regression Cases
```
---
# 5. FUNCTIONAL / INTEGRATION TESTS ARE MANDATORY
Every feature must have applicable Functional or Integration Tests.
These tests should validate how multiple parts of the application work together.
Examples include:
* API → Service → Database
* UI → API → Database
* Authentication → Authorization → Feature
* Form submission → Validation → Persistence
* External integration → Application handling
* Background job → Database updates
* Workflow transitions
* Multi-user or multi-role flows
Functional tests must validate actual feature behaviour rather than isolated implementation details.
---
# 6. UI/UX TESTS ARE A FIRST-CLASS REQUIREMENT
For any user-facing feature, UI/UX testing is **MANDATORY**.
UI/UX testing must not be treated as less important than backend testing.
Use the project's existing E2E/UI framework where available, such as:
```text
Playwright
Cypress
Selenium
WebdriverIO
Testing Library
or the project's existing equivalent.
```
Do NOT introduce a new testing framework unnecessarily if the repository already has one.
---
# 7. UI TESTS MUST VALIDATE FUNCTIONAL BEHAVIOUR
For user-facing functionality, test relevant workflows such as:
* Page loads correctly
* User can access the feature
* User can perform the intended action
* Forms can be completed
* Form submission works
* Validation messages appear
* Success messages appear
* Error states display correctly
* Data persists correctly
* Navigation works
* Modals/dialogs work
* Buttons and controls behave correctly
* Permissions affect UI correctly
* Loading states behave correctly
* Empty states are handled
* User can recover from errors
---
# 8. UX VALIDATION IS ALSO REQUIRED
Do not limit UI testing to:
> "The element exists."
Validate the actual user experience.
Where relevant, check:
* Clear labels
* Understandable error messages
* Form usability
* Logical navigation
* Disabled/loading states
* Confirmation feedback
* Empty states
* Error recovery
* Keyboard navigation
* Accessibility
* Responsive behaviour
* Visual hierarchy
* Consistency with existing design patterns
Where automated verification is possible, automate it.
Where subjective/manual UX verification is required, explicitly report it.
---
# 9. RESPONSIVE UI TESTING
For significant user-facing functionality, test representative viewport sizes where applicable.
For example:
```text
Desktop
Tablet
Mobile
```
At minimum verify that important workflows remain usable and no critical components become:
* Hidden
* Overlapping
* Unreachable
* Clipped
* Unreadable
* Unusable
---
# 10. ACCESSIBILITY
Where applicable, UI/UX tests should check:
* Semantic HTML
* Labels
* ARIA attributes
* Keyboard navigation
* Focus states
* Form accessibility
* Accessible error messages
* Dialog/modal focus behaviour
* Appropriate contrast where tooling supports it
Follow the application's existing accessibility standard where one exists.
---
# 11. TEST EXISTING BEHAVIOUR BEFORE CHANGING IT
Before implementing a change:
1. Inspect existing tests.
2. Understand existing expected behaviour.
3. Identify potentially affected functionality.
4. Preserve backward compatibility unless the requirement explicitly changes it.
For bug fixes:
> Whenever practical, first create a test reproducing the bug, verify that it fails, implement the fix, and verify that the test passes.
This creates a regression test preventing the issue from returning.
---
# 12. DO NOT DELETE TESTS JUST TO MAKE A BUILD PASS
Never:
* Remove legitimate tests because they fail after your change.
* Disable tests without justification.
* Add unconditional skips.
* Weaken assertions merely to obtain green tests.
* Change expected results simply to match incorrect implementation.
If expected behaviour intentionally changed, update tests and documentation to reflect the new requirement and explain why.
---
# 13. TEST QUALITY
Tests should be:
* Deterministic
* Maintainable
* Readable
* Isolated where practical
* Fast enough for their test level
* Meaningfully named
* Focused on behaviour
Avoid excessive mocking that causes tests to validate mocks instead of application behaviour.
---
# 14. TEST NAMING
Use descriptive test names.
Prefer:
```text
should reject leave request when end date is before start date
```
instead of:
```text
testLeave2
```
A developer should understand the behaviour being tested simply by reading the test name.
---
# 15. TEST TRACEABILITY
Whenever practical, document the relationship between:
```text
Requirement
↓
Implementation
↓
Unit Test
↓
Functional Test
↓
UI/UX Test
```
Important business rules should have identifiable corresponding tests.
---
# 16. TEST THE DELTA — EVERY TIME
For every coding request, you MUST automatically run the tests directly related to the changed functionality.
Do NOT ask whether feature-specific tests should be run.
They are mandatory.
At minimum:
```text
Changed functionality
↓
Relevant Unit Tests
↓
Relevant Functional Tests
↓
Relevant UI/UX Tests
```
must be executed before final completion.
---
# 17. FULL TEST SUITE — ASK THE DEVELOPER
In addition to mandatory feature-specific testing, you MUST ask the developer whether they want the **FULL project-wide test suites** executed.
Ask:
> "Feature-specific Unit, Functional, and UI/UX tests are mandatory and will be run automatically. Would you also like me to run the FULL repository-wide Unit, Functional/Integration, and UI/UX/E2E test suites?"
Options:
```text
A. Yes — run ALL full test suites.
B. No — run only mandatory feature-related tests.
```
Do not confuse these two concepts:
### Mandatory
Tests directly related to the current feature/change.
### Optional Full Suite
Every applicable test across the entire application/repository.
---
# 18. IF THE USER DOES NOT ANSWER THE FULL-SUITE QUESTION
Do NOT block development unnecessarily.
Proceed with:
```text
Mandatory feature-specific tests
```
and clearly state in the final report:
```text
Full repository-wide suite: Not requested / not executed.
```
---
# 19. EXISTING TEST FAILURES
If tests fail:
First determine whether the failure is:
```text
A. Caused by the current change
B. Pre-existing and unrelated
C. Environment/infrastructure related
D. Flaky
E. Unable to determine
```
If caused by the current change:
> Fix it before claiming completion.
If clearly pre-existing:
> Do not silently fix unrelated functionality unless appropriate.
Report the failure clearly.
---
# 20. TESTING PYRAMID
Use the appropriate testing level rather than attempting to test everything through the UI.
Prefer:
```text
/\
/ \
/ UI \
/ E2E \
/--------\
/Functional\
/Integration \
/--------------\
/ Unit Tests \
/__________________\
```
Use:
### Unit Tests
For isolated business logic.
### Functional / Integration Tests
For component/service/API interaction.
### UI/UX / E2E Tests
For critical user journeys.
Important functionality may require coverage at all three levels.
---
# 21. UI FEATURE EXAMPLE
If implementing:
```text
Employee Leave Request
```
do NOT stop after creating:
```text
POST /api/leave
```
The completed work should include, where applicable:
```text
Implementation
├── Leave form
├── Backend/API
├── Validation
├── Database persistence
└── Permissions
Documentation
└── docs/features/leave-management.md
Unit Tests
├── Date validation
├── Leave balance calculation
└── Business rules
Functional Tests
├── Create leave request
├── Invalid leave request
├── Unauthorized request
└── Database persistence
UI/UX Tests
├── Open leave form
├── Enter dates
├── Submit request
├── Show validation
├── Show success state
└── Verify leave appears in leave history
```
Only after these are complete and applicable tests pass should the functionality be declared complete.
---
# 22. CHANGE IMPACT ANALYSIS
Before coding, briefly identify:
```text
Feature being changed
Affected components
Affected APIs
Affected database entities
Affected user roles
Affected existing features
Documentation requiring updates
Unit tests required
Functional tests required
UI/UX tests required
```
This prevents hidden regressions.
---
# 23. DO NOT OVER-ENGINEER
Testing is mandatory, but implementation should remain proportional to the feature.
Do not:
* Introduce unnecessary frameworks
* Create unnecessary abstractions
* Rewrite unrelated components
* Add excessive dependencies
* Create hundreds of low-value tests
Aim for:
> Maximum confidence with maintainable implementation and meaningful coverage.
---
# 24. COMPLETION GATE
You are **NOT ALLOWED to say**:
```text
Done
Completed
Implemented
Finished
Feature is ready
Everything works
Task completed successfully
```
until you have checked:
```text
[ ] Implementation completed
[ ] Feature documentation created/updated
[ ] Unit tests created/updated
[ ] Unit tests executed
[ ] Functional/integration tests created/updated
[ ] Functional/integration tests executed
[ ] UI/UX/E2E tests created/updated where applicable
[ ] UI/UX/E2E tests executed where applicable
[ ] Relevant tests pass
[ ] Build/type-check/lint checks completed where applicable
[ ] Documentation matches final behaviour
[ ] Any failures/limitations explicitly documented
```
This checklist acts as the **Definition of Done**.
---
# 25. FINAL RESPONSE FORMAT
At the end of EVERY coding task, report:
```text
## Implementation
- What was implemented
- Major files changed
## Documentation
- Documentation created/updated:
- path/to/feature.md
## Unit Tests
- Tests added/updated:
- Tests executed:
- Result:
## Functional / Integration Tests
- Tests added/updated:
- Tests executed:
- Result:
## UI/UX / E2E Tests
- Tests added/updated:
- User flows covered:
- Tests executed:
- Result:
## Quality Checks
- Type check:
- Lint:
- Build:
- Other relevant checks:
## Full Test Suite
- Requested: Yes / No
- Executed: Yes / No
- Result:
## Remaining Issues
- None
OR clearly list outstanding problems.
## Final Status
COMPLETE
```
Only report:
```text
Final Status: COMPLETE
```
when all mandatory requirements have been satisfied.
Otherwise report:
```text
Final Status: INCOMPLETE
```
and explicitly state what remains.
---
# 26. WHEN A TEST TYPE IS NOT APPLICABLE
Do not fabricate meaningless tests simply to satisfy the checklist.
Instead document:
```text
UI/UX Tests: Not Applicable
Reason: Backend-only internal functionality with no user-facing behaviour.
```
Likewise for any genuinely non-applicable test category.
The reason must be explicit.
---
# 27. EXISTING PROJECT CONVENTIONS TAKE PRIORITY
Before creating tests or documentation:
1. Inspect the repository.
2. Identify existing conventions.
3. Identify existing test frameworks.
4. Identify test directory structure.
5. Identify documentation structure.
6. Follow established naming and architectural patterns.
Do not introduce competing patterns unless there is a strong technical reason.
---
# 28. NEVER CLAIM A TEST PASSED IF IT WAS NOT EXECUTED
Use precise terminology.
Only say:
```text
PASS
```
if the test was actually executed and passed.
Otherwise say:
```text
NOT RUN
BLOCKED
NOT APPLICABLE
FAILED
```
Never infer that something works simply because the code looks correct.
---
# 29. SOURCE OF TRUTH
For every feature:
```text
Requirements
+
Implementation
+
Feature Documentation
+
Automated Tests
```
must remain synchronized.
If these conflict, investigate and resolve the inconsistency before declaring completion.
---
# 30. PERMANENT INSTRUCTION
Treat everything in this document as a **standing repository rule**.
I should NOT need to repeat:
> "Add tests."
I should NOT need to repeat:
> "Update documentation."
I should NOT need to repeat:
> "Test the UI."
I should NOT need to repeat:
> "Run tests before saying done."
For every future coding task, automatically enforce:
> **IMPLEMENT → DOCUMENT → UNIT TEST → FUNCTIONAL TEST → UI/UX TEST → VERIFY → REPORT**
Feature-specific tests are mandatory.
The only testing question you should normally ask me is:
> **"Would you also like the FULL repository-wide Unit, Functional/Integration, and UI/UX/E2E suites to be executed?"**
This rule remains active for **every coding request unless I explicitly override it for a specific task.**