114 lines
4.5 KiB
Markdown
114 lines
4.5 KiB
Markdown
# Documentation Management - Purchase Trade
|
|
|
|
This guide records the documentation workflow to apply for future `purchase_trade` developments.
|
|
|
|
## Rule Documentation Structure
|
|
|
|
- Keep `business-rules.md` as the entry point and rule catalog.
|
|
- Store detailed business rules in `docs/business rules/`, one file per substantial rule.
|
|
- Use stable business rule IDs such as `BR-PT-004`.
|
|
- Add every new detailed rule to the catalog in `business-rules.md`.
|
|
- Keep rule files focused on business behavior, expected outcomes, edge cases, impacted files, tests, and open questions.
|
|
|
|
## Rule File Template
|
|
|
|
Use this structure for detailed rule files when applicable:
|
|
|
|
- Intent
|
|
- Scope
|
|
- Inputs
|
|
- Date and Numeric Parsing, when relevant
|
|
- Expected Behavior
|
|
- Defaults or Derived Values, when relevant
|
|
- Result Reporting, when relevant
|
|
- Edge Cases
|
|
- Impacted Files
|
|
- Tests
|
|
- Open Questions
|
|
|
|
## Open Questions
|
|
|
|
- In `Open Questions`, prefix every question with `Q:`.
|
|
- Prefix every documented answer with `A:`.
|
|
- When an answer differs from current code behavior, add a short `Comment:` explaining that a code change is required.
|
|
- Once all questions have answers, keep the section as decision history unless the rule becomes noisy.
|
|
|
|
Example:
|
|
|
|
```md
|
|
- Q: Should missing `price_value` be allowed?
|
|
- A: Missing `price_value` is not allowed. Report the row as an error.
|
|
- Comment: current code allows empty `price_value`. Implementing this answer requires a code change.
|
|
```
|
|
|
|
|
|
|
|
## Backlog From Documentation
|
|
|
|
- When answered questions imply code changes, create a dedicated backlog file for the feature or rule.
|
|
- Store all backlog files in `docs/backlog/`.
|
|
- Name backlog files by feature, for example `docs/backlog/market-price-import-backlog.md`.
|
|
- Do not use a generic module backlog when the changes belong to one feature.
|
|
- After coding a backlog item, update that item with the work done and mark its `Status` as `to be tested` until the targeted validation has run successfully in the proper environment.
|
|
- After committing implemented backlog work, record the implementation commit hash in the relevant backlog item for future reference.
|
|
- Each backlog item should include:
|
|
- stable ID
|
|
- status
|
|
- implementation commit, once committed
|
|
- priority
|
|
- source rule file
|
|
- requirement
|
|
- work done, once implemented
|
|
- validation status, once attempted
|
|
- current behavior, when useful
|
|
- expected code impact
|
|
- expected tests
|
|
|
|
Backlog status values:
|
|
|
|
- `open`: identified, not started yet
|
|
- `in-progress`: currently being worked on
|
|
- `blocked`: cannot progress until a dependency or question is resolved
|
|
- `implemented`: code or documentation change made, not yet validated
|
|
- `to-be-tested`: implemented and waiting for targeted validation in the right environment
|
|
- `tested`: targeted validation passed
|
|
- `done`: tested, committed, and no further action expected
|
|
- `rejected`: intentionally not implemented
|
|
|
|
Default workflow:
|
|
|
|
```text
|
|
open -> in-progress -> to-be-tested -> tested -> done
|
|
```
|
|
|
|
Use `implemented` only when the change is made but no validation attempt has happened yet. Use `to-be-tested` when validation must happen in another environment or could not be completed locally.
|
|
|
|
## Bug Management
|
|
|
|
- Register every new bug in `docs/bugs.md`.
|
|
- Use stable bug IDs such as `BUG-PT-001`.
|
|
- Every new bug must have a matching backlog entry.
|
|
- Link the bug entry to its backlog entry.
|
|
- If the bug belongs to an existing feature backlog, add it there.
|
|
- If the bug does not clearly belong to an existing feature backlog, create a dedicated backlog file under `docs/backlog/`.
|
|
- When the bug is fixed, record the implementation commit in the backlog entry and update the bug status.
|
|
|
|
## Review Workflow
|
|
|
|
For future development work:
|
|
|
|
1. Read the relevant rule file before changing code.
|
|
2. Review the current code and tests related to the rule.
|
|
3. Update the rule documentation if code review reveals missing behavior, edge cases, defaults, or test gaps.
|
|
4. Record unresolved decisions as `Q:` entries.
|
|
5. Record accepted decisions as `A:` entries.
|
|
6. Convert accepted decisions that require code changes into backlog items.
|
|
7. Implement code only after the requested documentation/specification step is complete, or after explicit approval when the user asks to wait.
|
|
|
|
## Scope Discipline
|
|
|
|
- Keep documentation changes close to the affected module and feature.
|
|
- Do not mix unrelated features in one rule file or one backlog file.
|
|
- Link or list impacted files so future agents can work in a narrow code scope.
|
|
- Keep tests listed near the rule they validate.
|