tradon/modules/purchase_trade/docs/documentation-management.md

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:

- 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:

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.