docs(evidence): finalize restructuring design
This commit is contained in:
@@ -0,0 +1,76 @@
|
||||
# Domain documentation
|
||||
|
||||
This repository uses a single-context domain-documentation layout.
|
||||
|
||||
## Sources
|
||||
|
||||
Before changing behavior or terminology, read:
|
||||
|
||||
1. `CONTEXT.md` at the repository root;
|
||||
2. any relevant architectural decision records under `docs/adr/`;
|
||||
3. the implementation and tests for the affected module.
|
||||
|
||||
`CONTEXT.md` contains the shared domain vocabulary and the system's main
|
||||
concepts. Use its terminology consistently in code, documentation, issues, and
|
||||
user-facing explanations.
|
||||
|
||||
ADRs explain important architectural decisions and their rationale. They are
|
||||
created only when a durable decision needs to be recorded; the absence of
|
||||
`docs/adr/` is not an error.
|
||||
|
||||
If one of these optional sources does not exist, continue without reporting an
|
||||
error.
|
||||
|
||||
## Layout
|
||||
|
||||
```text
|
||||
/
|
||||
├── CONTEXT.md
|
||||
└── docs/
|
||||
└── adr/
|
||||
└── <decision>.md
|
||||
```
|
||||
|
||||
Do not introduce `CONTEXT-MAP.md` unless the repository later becomes a
|
||||
genuine multi-context system whose domains require separate context documents.
|
||||
|
||||
## Working with domain concepts
|
||||
|
||||
When implementing or reviewing work:
|
||||
|
||||
- identify the domain concepts involved;
|
||||
- reuse the names defined in `CONTEXT.md`;
|
||||
- distinguish domain rules from infrastructure details;
|
||||
- avoid creating synonyms for established terms;
|
||||
- update `CONTEXT.md` when a new durable concept is introduced or an existing
|
||||
definition materially changes.
|
||||
|
||||
For ThothII, the Evidence module and its concepts belong to this shared domain
|
||||
context even though Evidence is implemented as an autonomous workflow module.
|
||||
|
||||
## Architectural decisions
|
||||
|
||||
Create an ADR when a decision:
|
||||
|
||||
- affects multiple parts of the system;
|
||||
- establishes a durable constraint;
|
||||
- selects between meaningful alternatives;
|
||||
- would otherwise be difficult to reconstruct later.
|
||||
|
||||
Do not create an ADR for routine implementation details.
|
||||
|
||||
If current code or a proposed change conflicts with an ADR, flag the conflict
|
||||
explicitly. Do not silently override the recorded decision.
|
||||
|
||||
## Keeping documentation aligned
|
||||
|
||||
When a change affects the domain model:
|
||||
|
||||
1. update the implementation;
|
||||
2. update the relevant tests;
|
||||
3. update `CONTEXT.md`;
|
||||
4. add or update an ADR when the decision is architectural;
|
||||
5. update linked plans and GitHub issues.
|
||||
|
||||
The persisted repository documentation, not the chat transcript, is the
|
||||
long-term source of truth.
|
||||
@@ -0,0 +1,165 @@
|
||||
# Issue tracker: GitHub
|
||||
|
||||
Issues and specifications for this repository live in GitHub Issues under
|
||||
`mptyl/ThothII`.
|
||||
|
||||
Use the GitHub CLI (`gh`) for issue operations. Infer the repository from the
|
||||
current Git remote when possible.
|
||||
|
||||
## Conventions
|
||||
|
||||
Create an issue:
|
||||
|
||||
```bash
|
||||
gh issue create --title "<title>" --body-file <file>
|
||||
```
|
||||
|
||||
Read an issue:
|
||||
|
||||
```bash
|
||||
gh issue view <number>
|
||||
```
|
||||
|
||||
List issues:
|
||||
|
||||
```bash
|
||||
gh issue list
|
||||
```
|
||||
|
||||
Add a comment:
|
||||
|
||||
```bash
|
||||
gh issue comment <number> --body-file <file>
|
||||
```
|
||||
|
||||
Apply or remove labels:
|
||||
|
||||
```bash
|
||||
gh issue edit <number> --add-label "<label>"
|
||||
gh issue edit <number> --remove-label "<label>"
|
||||
```
|
||||
|
||||
Close an issue:
|
||||
|
||||
```bash
|
||||
gh issue close <number>
|
||||
```
|
||||
|
||||
## Pull requests as a triage surface
|
||||
|
||||
Pull requests are not used as the primary request or triage surface.
|
||||
|
||||
A pull request may implement or resolve an issue, but the issue remains the
|
||||
canonical location for:
|
||||
|
||||
- the request;
|
||||
- its scope and acceptance criteria;
|
||||
- triage status;
|
||||
- dependencies and sub-issues;
|
||||
- implementation progress;
|
||||
- the final resolution summary.
|
||||
|
||||
## Publishing work
|
||||
|
||||
When a workflow or skill says to publish a plan, specification, finding, or
|
||||
request, create or update a GitHub issue.
|
||||
|
||||
Do not leave the only authoritative copy in a chat transcript.
|
||||
|
||||
Long implementation documents may also be committed to the repository. In that
|
||||
case, the corresponding issue should link to the committed document and track
|
||||
its execution status.
|
||||
|
||||
## Fetching work
|
||||
|
||||
When a workflow or skill refers to an issue number, retrieve the current issue
|
||||
and its comments before acting:
|
||||
|
||||
```bash
|
||||
gh issue view <number> --comments
|
||||
```
|
||||
|
||||
Treat the live issue state as authoritative for assignment, labels, closure,
|
||||
and subsequent decisions.
|
||||
|
||||
## Wayfinding operations
|
||||
|
||||
A wayfinding map is represented by a parent GitHub issue and, when useful,
|
||||
smaller child issues.
|
||||
|
||||
### Map
|
||||
|
||||
Create or update one parent issue describing:
|
||||
|
||||
- the intended outcome;
|
||||
- relevant context;
|
||||
- known constraints;
|
||||
- the proposed decomposition;
|
||||
- dependencies between tasks;
|
||||
- completion criteria.
|
||||
|
||||
Label it according to `docs/agents/triage-labels.md`.
|
||||
|
||||
### Child issues
|
||||
|
||||
Create a separate issue for each independently actionable unit of work.
|
||||
|
||||
Keep the parent issue readable: summarize the decomposition there and link the
|
||||
child issues instead of copying every implementation detail.
|
||||
|
||||
When GitHub sub-issues are available, register the relationship through the
|
||||
GitHub API. Otherwise, maintain a checklist of linked child issues in the
|
||||
parent issue.
|
||||
|
||||
### Dependencies
|
||||
|
||||
Represent blocking relationships with GitHub's native issue-dependency API
|
||||
when available.
|
||||
|
||||
First obtain the database ID of the blocking issue:
|
||||
|
||||
```bash
|
||||
gh api repos/mptyl/ThothII/issues/<blocking-number> --jq '.id'
|
||||
```
|
||||
|
||||
Then register it as a blocker:
|
||||
|
||||
```bash
|
||||
gh api \
|
||||
--method POST \
|
||||
repos/mptyl/ThothII/issues/<blocked-number>/dependencies/blocked_by \
|
||||
-F issue_id=<blocking-issue-database-id>
|
||||
```
|
||||
|
||||
If native dependencies are unavailable, record the relationship explicitly in
|
||||
both issues.
|
||||
|
||||
### Frontier
|
||||
|
||||
The frontier is the set of open child issues that:
|
||||
|
||||
- have no unresolved blockers;
|
||||
- are sufficiently specified;
|
||||
- can be worked on independently;
|
||||
- are not already being worked on.
|
||||
|
||||
Use labels and current issue relationships to identify the frontier.
|
||||
|
||||
### Claim
|
||||
|
||||
Before starting an issue:
|
||||
|
||||
1. confirm that it is still open and unblocked;
|
||||
2. assign it to the current operator when appropriate;
|
||||
3. apply the label `ready-for-agent` only if it is genuinely executable;
|
||||
4. add a short comment stating that work has started.
|
||||
|
||||
### Resolve
|
||||
|
||||
When the work is complete:
|
||||
|
||||
1. verify the issue's acceptance criteria;
|
||||
2. add a concise resolution comment with relevant files, tests, or decisions;
|
||||
3. update the parent issue or dependent issues;
|
||||
4. close the issue;
|
||||
5. reconsider the frontier, because resolving a blocker may unlock more work.
|
||||
@@ -0,0 +1,19 @@
|
||||
# Triage labels
|
||||
|
||||
These labels represent workflow roles rather than subject areas.
|
||||
|
||||
| Label | Meaning |
|
||||
| --- | --- |
|
||||
| `needs-triage` | The request has not yet been classified or evaluated. |
|
||||
| `needs-info` | More information or a human decision is required before work can proceed. |
|
||||
| `ready-for-agent` | The work is sufficiently specified, unblocked, and suitable for an agent. |
|
||||
| `ready-for-human` | The work requires human review, approval, or an action only a human can perform. |
|
||||
| `wontfix` | The request has been deliberately declined or will not be implemented. |
|
||||
|
||||
Use only the labels that describe the issue's current workflow state.
|
||||
|
||||
Remove obsolete workflow labels when the state changes. For example, remove
|
||||
`needs-info` when the missing information has been supplied.
|
||||
|
||||
Subject-area labels may be added separately, but they must not replace these
|
||||
workflow roles.
|
||||
Reference in New Issue
Block a user