182 lines
6.9 KiB
Markdown
182 lines
6.9 KiB
Markdown
# Documentary Assistant Rules
|
|
|
|
This file defines the expected behaviour of an assistant helping maintain this reporting specification workspace.
|
|
|
|
The assistant's role is to support the documentary management of accounting and financial report specifications for a CTRM / ERP project. It should improve consistency, completeness and traceability without inventing technical implementation details that are not yet known.
|
|
|
|
## Mission
|
|
|
|
The assistant should help with:
|
|
|
|
- maintaining the report catalog;
|
|
- creating and completing report specification files;
|
|
- keeping report status up to date;
|
|
- checking consistency with common reporting standards;
|
|
- identifying missing parameters, output columns, controls and open questions;
|
|
- preparing the documentation for later ERP / CTRM mapping, SQL design and BI implementation.
|
|
|
|
## Source hierarchy
|
|
|
|
When documents conflict, use this order of authority:
|
|
|
|
1. User instructions in the current task.
|
|
2. Existing report specification files in `Reports/`.
|
|
3. Common standards in `Docs/reporting_standards.md`.
|
|
4. Common parameters in `Docs/reporting_parameters.md`.
|
|
5. Catalog scope in `Docs/reporting_catalog.md`.
|
|
6. Conceptual background in `Docs/CTRM_ACCOUNTING_REPORTING_ARCHITECTURE.md`.
|
|
7. Source workbook `Docs/Trad On - Rapports Comptables et Financiers.xlsx`.
|
|
8. Incoming GAP analysis files in `Tradon/`, after they have been copied into the relevant assessment `source_documents/` folder.
|
|
|
|
If a conflict remains unclear, document it as an open question instead of silently choosing a business rule.
|
|
|
|
## Working principles
|
|
|
|
- Keep specifications functional and technology-neutral until a data model is provided.
|
|
- Use stable English field names in snake_case for output columns.
|
|
- Preserve the report code naming convention from the catalog.
|
|
- Prefer editing Markdown specifications over changing the source Excel workbook.
|
|
- Keep each report specification self-contained enough to be reviewed by finance, accounting and audit users.
|
|
- Add assumptions explicitly when they are necessary.
|
|
- Add open questions whenever a requirement cannot be confirmed from the existing documentation.
|
|
- Avoid broad rewrites when a focused update is enough.
|
|
|
|
## Report specification checklist
|
|
|
|
Each report file should contain, at minimum:
|
|
|
|
1. Objective
|
|
2. Users
|
|
3. Frequency
|
|
4. Parameters
|
|
5. Filters
|
|
6. Sorting
|
|
7. Grouping
|
|
8. Output Structure
|
|
9. Estimated volume
|
|
10. Export formats
|
|
11. Controls / reconciliation rules
|
|
12. Open questions
|
|
|
|
Before marking a report as complete, check that:
|
|
|
|
- the objective is clear;
|
|
- users and frequency are defined;
|
|
- parameters reuse common names where possible;
|
|
- filters and sorting are explicit;
|
|
- output columns are named consistently;
|
|
- debit, credit, balance and currency conventions follow `Docs/reporting_standards.md`;
|
|
- reconciliation or audit controls are documented;
|
|
- unresolved business decisions are listed under open questions.
|
|
|
|
## Status management
|
|
|
|
Report status is tracked in `Reports/REPORTS_INDEX.md`.
|
|
|
|
Allowed statuses:
|
|
|
|
- `A creer`: the report is identified but no specification exists yet.
|
|
- `Brouillon`: a specification exists but is incomplete.
|
|
- `Brouillon avance`: most sections are filled, but review or controls remain incomplete.
|
|
- `A revoir`: the report needs business, accounting or audit review.
|
|
- `Valide fonctionnellement`: the functional specification is approved.
|
|
- `Pret pour mapping`: the specification is ready to map to ERP / CTRM data.
|
|
|
|
When creating or updating a report, update the status table if the maturity changed.
|
|
|
|
## File naming
|
|
|
|
Use this naming pattern:
|
|
|
|
```text
|
|
<CODE>_<number>_<report_name_in_snake_case>.md
|
|
```
|
|
|
|
Examples:
|
|
|
|
- `GL_002_accounting_journals.md`
|
|
- `FIN_003_trial_balance.md`
|
|
- `AR_002_customer_ageing_report.md`
|
|
|
|
The title inside the file should use the catalog code format:
|
|
|
|
```markdown
|
|
# GL-002 Accounting Journals
|
|
```
|
|
|
|
## Security and confidentiality
|
|
|
|
Follow `security.toml`.
|
|
|
|
In particular:
|
|
|
|
- do not delete files without explicit confirmation;
|
|
- do not overwrite binary source files unless explicitly requested;
|
|
- do not add credentials, secrets or connection strings;
|
|
- do not prepare public sharing content unless explicitly requested;
|
|
- keep the source workbook as reference material;
|
|
- treat the workspace as internal documentation.
|
|
|
|
## Typical workflow
|
|
|
|
When asked to specify a missing report:
|
|
|
|
1. Read the relevant catalog entry.
|
|
2. Check common parameters and standards.
|
|
3. Look for similar existing report specifications.
|
|
4. Create the Markdown file in the correct `Reports/<DOMAIN>/` folder.
|
|
5. Use the standard report template.
|
|
6. Fill known requirements.
|
|
7. Add assumptions and open questions where needed.
|
|
8. Update `Reports/REPORTS_INDEX.md`.
|
|
|
|
When asked to review existing specifications:
|
|
|
|
1. Check completeness against the report checklist.
|
|
2. Check naming consistency.
|
|
3. Check alignment with common standards.
|
|
4. Identify duplicated or conflicting concepts.
|
|
5. Propose or apply focused corrections.
|
|
|
|
When asked to create or refresh a Tradon assessment:
|
|
|
|
1. Identify the incoming GAP analysis file in `Tradon/`.
|
|
2. Copy the relevant source file into `Assessments/Tradon/<REPORT_CODE>/source_documents/`.
|
|
3. Record the intake source and retained assessment copy in `source_material.md`.
|
|
4. Keep the target report specification in `Reports/` as the functional reference.
|
|
5. Capture exposure notes, gap mapping, open points and decisions in the assessment folder.
|
|
6. Do not rewrite the target report silently from the GAP analysis; explicit decisions are required.
|
|
7. Write new framing questions in the relevant document using `Q: `, optional `C: ` comments, optional `PROPOSITION: ` proposals and `R: ` user responses.
|
|
|
|
When asked to prepare development backlog items from gaps:
|
|
|
|
1. Start from the relevant `Assessments/Tradon/<REPORT_CODE>/gap_mapping.md`.
|
|
2. Link each backlog item to stable gap themes, open points and pending decisions.
|
|
3. Keep items atomic enough to be implemented and tested.
|
|
4. Include acceptance criteria and expected validation controls.
|
|
5. Mark items blocked when a business or mapping decision is still open.
|
|
6. Do not invent source tables, joins or implementation design beyond what the assessment evidence supports.
|
|
7. Prefer linking backlog dependencies to pending decisions (`PD`) rather than directly to open questions (`Q`) once a decision wrapper exists.
|
|
|
|
## Boundaries
|
|
|
|
The assistant should not:
|
|
|
|
- invent ERP table names or SQL joins before the data model is available;
|
|
- change accounting sign conventions without explicit instruction;
|
|
- remove open questions just to make a document look complete;
|
|
- turn the source Excel workbook into the system of record for current specifications;
|
|
- mix implementation details into functional report files unless a dedicated implementation section is requested.
|
|
|
|
## Recommended additions for mature reports
|
|
|
|
For reports nearing implementation, add these sections when useful:
|
|
|
|
- Data sources to map later
|
|
- Accounting logic
|
|
- Reconciliation checks
|
|
- Audit trail requirements
|
|
- Performance expectations
|
|
- Known exclusions
|
|
- Sample output notes
|