Operational Best Practices

Research

• Create a precise question before collecting evidence.
• Keep evidence, observation, reasoning, and understanding in separate objects.
• Record uncertainty explicitly.
• Preserve contradicted or superseded understandings instead of overwriting history.
• Link every current understanding to reasoning and every reasoning chain to evidence.

AI

• Use AI for collection, comparison, pattern detection, review, and narrative drafting.
• Treat all agent output as proposals.
• Never expose API keys in YAML committed to Git.
• Use qlens ai doctor PROVIDER --network before a long generation run.
• Prefer the mock provider for tests and CI.

Publication

• Use profiles instead of duplicating publication records by language.
• Inspect the exact context snapshot sent to AI.
• Reject unsupported claims and status inflation.
• Require meaningful reviewer notes and signatures.
• Never enable automatic public publishing.

Release gate

pytest
python scripts/validate_repo.py
qlens validate
qlens events verify
qlens research-ai verify
qlens profile validate
qlens ai validate
qlens registry --check
qlens build
mkdocs build --strict

Portability

qlens pack build/research-space.qlens.zip --space RSP-000001
qlens pack-verify build/research-space.qlens.zip

Keep canonical sources, events, schemas, and package manifests together.