DevRunbook-Public/docs/02-personas-and-jobs.md

02 — Personas and jobs-to-be-done

Persona A — Independent builder

Uses Codex for personal products, prototypes and self-hosted tools. Has several repositories with different stacks and repeatedly copies long instructions.

Jobs:

• “When I start a recurring development task, give me a proven structure so I do not forget validation or safety constraints.”
• “When I return to an older repository, reuse its real commands and conventions.”
• “When I ask Codex to work autonomously, show exactly what autonomy I am granting.”

Pain points:

• scattered prompts in notes and prior chats;
• prompts become stale when a repository changes;
• inconsistent results between projects;
• lack of evidence that Codex actually validated the change.

Persona B — Infrastructure and operations engineer

Works across scripts, containers, automation, M365 tooling, internal portals and operational repositories. Values safe, reversible work and clear support handoffs.

Jobs:

• generate audits that separate observations from recommendations;
• prepare cleanup or hardening tasks without breaking deployments;
• standardize backup, restore, logging and release checks;
• produce a clear final report suitable for future troubleshooting.

Persona C — Engineering lead or reviewer

Wants team members and agents to use consistent standards without maintaining one giant global prompt.

Jobs:

• publish reviewed playbooks;
• enforce validation and reporting requirements;
• compare versions and review changes;
• know which playbook and repository context produced a task;
• prevent unsafe community content from appearing trusted.

Persona D — Playbook author

Creates and maintains reusable workflows for particular technologies or task types.

Jobs:

• define typed inputs and conditional blocks;
• preview output with representative profiles;
• lint ambiguity and missing controls;
• attach evaluation cases and changelogs;
• publish a new version without mutating previous runs.

Persona E — Self-hosted platform operator

Deploys DevRunbook on Docker or Unraid and manages storage, backups, upgrades and integrations.

Jobs:

• deploy from a documented compose configuration;
• keep secrets out of logs and backups where appropriate;
• see failed jobs and integration health;
• back up and restore the platform;
• upgrade with reversible migrations.

Key usage scenarios

Scenario 1 — Audit a repository without changing it

1. User searches for “repository health”.
2. Selects the read-only audit playbook.
3. Selects a repository profile.
4. Chooses Observe autonomy.
5. Reviews detected stack, scope and exclusions.
6. Exports a prompt requiring an evidence-based report and no changes.

Scenario 2 — Fix a reproducible bug

1. User selects Root-Cause Bug Fix.
2. Provides the symptom and any error text.
3. Selects Verify autonomy.
4. Composer requires reproduction, regression test and relevant test commands.
5. Generated task forbids deleting behavior or weakening tests.
6. Run history preserves the exact task.

Scenario 3 — Build a new feature autonomously

1. User selects a feature implementation playbook.
2. Adds functional requirements and explicit exclusions.
3. Chooses a repository profile.
4. Defines permitted modules and protected paths.
5. Selects Repair autonomy.
6. Exports a Run Pack with specification, workflow, validation and handoff files.

Scenario 4 — Inspect Gitea governance

1. Operator connects Gitea using a read-only token.
2. Selects a repository.
3. DevRunbook snapshots branch protection, default branch, templates, release and workflow evidence where supported.
4. The workspace shows gaps with source evidence.
5. User launches the matching Gitea Best Practices playbook.

Scenario 5 — Author and validate a private playbook

1. Author creates a draft from a template.
2. Adds typed inputs and conditional validation rules.
3. Prompt Lab renders several examples.
4. Linter finds ambiguous scope and missing failure behavior.
5. Author corrects the package and adds a changelog.
6. Reviewer publishes version 1.0.0.