Proqi Debug

Diagnose one reported failure safely. Begin read-only and minimize access to scratchpad content.

Workflow

1. Run proqi --version and proqi --json capabilities. Require the supported JSON schema, doctor in data.commands, and the exact diagnostic operation before using it. If the installed version does not advertise a command, report that limitation instead of guessing. Then run the read-only health report proqi --json doctor. Preserve every doctor check ID, status, and remediation exactly. Doctor never repairs, migrates, initializes, or recreates canonical Proqi state.
2. Record the installed version, CLI schema version, operating system, terminal, exact invocation, approximate failure time, and smallest reproduction.
3. Preserve the exact stable error.code, error.message, and error.details from JSON commands. Do not strengthen an intermittent symptom into a confirmed defect.

4. Ask before collecting local diagnostics. In explicitly authorized unattended QA mode, this approval is satisfied only for diagnostics produced from the run's isolated QA state. Never collect from the user's normal Proqi state in unattended mode. Use an explicit private output path that does not already exist:

   proqi diagnostics collect --output proqi-diagnostics.json

5. Review the bundle locally before quoting or attaching it. It is designed to omit thought text, clipboard content, session names, workspace paths, pane identifiers, and raw external responses, but it retains typed identifiers and timestamps.
6. Correlate lifecycle events, command failures, and submission transitions by time and typed identifier. Never infer delivery failure merely from a later agent readiness state.
7. Reproduce with the smallest safe test session where practical. Do not read unrelated sessions or copy the user's live database merely for convenience.
8. Read references/storage.md only when the failure involves persistence, migrations, leases, undo history, or submissions. For history reports, first identify the scope: Browser history owns session rename, trash, and restore; Board history owns item and transformation operations inside one session; editor history owns exact replacements for one thought.
9. Classify the result as expected behavior, configuration or environment, unsupported integration, unconfirmed defect, confirmed defect, or security concern. State the evidence and any missing verification.

Local files

Proqi uses the operating system's native application data directory. Diagnostic segments are inside its diagnostics subdirectory, and the database is proqi.sqlite3 in the data directory.

• macOS: ~/Library/Application Support/proqi/
• Linux: ${XDG_DATA_HOME:-~/.local/share}/proqi/

Prefer proqi diagnostics collect over reading JSONL segments directly. Never edit the live database, its -wal or -shm files, lock metadata, backups, or diagnostic logs. Never run repair SQL against user data.

Prepare an issue

For a confirmed non-security defect, first search existing Issues at https://github.com/oborchers/proqi/issues. Then draft the exact issue title and body in chat. Include:

• Proqi version and CLI schema version.
• Operating system and terminal.
• Minimal reproduction steps.
• Expected and observed behavior.
• Stable error code and a short content-redacted diagnostic excerpt.
• Whether the failure is reproducible and whether data was modified or lost.

Remove thought text, clipboard data, credentials, personal paths, session names, pane identifiers, and identifiers that are not required to correlate the failure. Do not attach the diagnostic bundle by default.

By default, obtain explicit approval of the complete issue text before running gh issue create. Opening the issue is an external mutation. Report the issue URL only after the command succeeds.

An unattended QA goal may provide advance authorization to create issues without per-issue approval. Use that exception only when the goal explicitly names this skill, restricts testing to an identified released binary, requires repeated reproduction, defines a severity model, requires duplicate search, and authorizes automatic GitHub issue creation. In that mode:

1. Create issues only for confirmed non-security defects reproduced at least twice on the identified released binary from isolated QA state.
2. Search open and closed issues first. Do not create a duplicate.
3. Use only existing repository labels. Do not create or edit labels, milestones, projects, repository settings, or releases.
4. Sanitize the complete title and body locally before creation.
5. Do not attach or upload diagnostics, logs, screenshots, databases, or other local evidence.
6. Create exactly one issue for each independently confirmed root defect, verify the created issue, and record its URL in the QA report.
7. If any prerequisite is uncertain, keep the finding local as unconfirmed or blocked instead of publishing it.

Never open a public issue for a suspected security vulnerability. Follow SECURITY.md and use GitHub private vulnerability reporting instead. A private security submission still requires explicit approval unless the unattended goal separately and explicitly authorizes that exact channel.

Boundaries

• Do not mutate SQLite or bypass Proqi's CLI, owner channel, or leases.
• Do not emulate a semantic mutation with TUI keys. Active and inactive JSON writes must converge through the same application owner and durable receipt.
• Do not upload logs, bundles, databases, screenshots, or thought content.
• Do not retry a submission whose durable state is outcome_unknown.
• Do not claim a fix or successful delivery without direct evidence.
• Do not open, comment on, or modify a GitHub issue without explicit approval, except for new issues created within the narrow unattended QA authorization above.