End-to-End Research Workflow¶

This workflow shows a safe sequence from question creation to publication.

1. Inspect available Research Spaces¶

qlens list --type research_space
qlens show RSP-000001

2. Create the research question¶

qlens new question \
  "What does the available evidence establish?" \
  --space RSP-000001

Record the OID printed by the command.

3. Add evidence¶

qlens new evidence \
  "Observation from the primary source" \
  --space RSP-000001

Open the generated YAML file and complete its evidence-specific fields. Object creation produces a valid scaffold, not a completed research claim.

4. Add an observation and reasoning object¶

qlens new observation \
  "Direct observation from EVD-000002" \
  --space RSP-000001

qlens new reasoning \
  "Reasoning connecting the observation to the question" \
  --space RSP-000001

Edit the generated YAML record to add the required premise, conclusion, and relationship references defined by the contracts and schemas.

5. Validate early¶

qlens repo validate

Do not wait until publishing. Validation should happen after every meaningful research change.

6. Inspect relationships¶

qlens graph RSN-000002 --depth 2

Confirm that the reasoning object reaches the intended evidence, observation, question, and understanding objects.

7. Create a working understanding¶

qlens new current_understanding \
  "Current understanding based on the verified chain" \
  --space RSP-000001

An understanding must remain traceable to reasoning. Do not use status transitions to imply certainty that the graph does not support.

8. Query the space¶

qlens query "space=RSP-000001 and status=active"
qlens query "type=evidence and space=RSP-000001" --json

9. Move objects through lifecycle states¶

qlens transition QST-000002 collecting --note "Evidence collection opened"
qlens transition QST-000002 review --note "Question and evidence chain ready for review"

Only allowed transitions succeed.

10. Build derived views¶

qlens build

11. Preview NUR¶

mkdocs serve

Review the Research Workspace dashboard, object metadata, backlinks, graph, and timeline.

12. Package the Research Space¶

mkdir -p dist
qlens pack dist/research-space-RSP-000001.zip --space RSP-000001 --include-history

13. Commit canonical changes¶

git status
git add repository/objects repository/history docs mkdocs.yml

git commit -m "Add research chain for the current question"

Review generated files before committing. A project may choose to commit registries and rendered views or regenerate them in CI, but that policy must remain consistent.