Instruction file imported from msfasha/raseen-customer-agent (
.cursor/rules/documentation.mdc). Copyright stays with the author.
Documentation standard
When writing or editing code in this repo, documentation must explain workflow and algorithm, not only a one-line summary.
Required on every function/method
- Summary — purpose in one sentence.
- Why / when — where it sits in the call flow.
- Workflow / algorithm — numbered steps: loops (outer vs inner), branches, early returns, what is skipped.
- Args / Returns / Raises (Google style).
- Side effects — HTTP, Matrix, DB, crypto store, typing, etc.
Bad (too thin):
"""Mark peer devices as verified."""Good (expected depth):
"""Auto-trust peer devices so E2EE outbound sends work in demos.
Why:
nio will not encrypt to unverified devices; demos skip interactive SAS.
Workflow:
1. No device store → return.
2. Outer loop over room member user ids.
3. Inner loop over that user's active devices in the local store.
4. Skip the agent's own device; verify any unverified peer device.
5. Missing user in store (KeyError) → continue.
Side effects:
Updates local device verification flags only.
"""Also required
- Module docstring (ownership + stack role).
- Section banners that state the block’s purpose, not only a title.
- Downstream APIs called out as FastAPI/Uvicorn, not Flask.
- Keep docs synced with behavior. Skip
.venv/.
See root CLAUDE.md.