Skip to content

docs(skills): recover missing focus via sibling SnapshotDB choice - #156

Merged
codeasier merged 1 commit into
mainfrom
feat/issue-151-sibling-db-docs
Sep 23, 2026
Merged

codeasier merged 1 commit into
mainfrom
feat/issue-151-sibling-db-docs

Conversation

@codeasier

Copy link
Copy Markdown
Owner

📝 Description

Add a helper and diagnostic-skill recovery rule for when the effective focus path is missing but sibling *.db / *.pickle.db files exist. Agents must list candidates without auto-selecting, wait for an explicit user choice, then inspect with pt-snap metadata --json. They must not persist focus, import pickle, run query/report before confirmation, or inherit the old focused device.

Existing missing-database e2e coverage stays the explicit-missing-path branch. This PR adds sibling-database-recovery.

🔗 Related Issue

Fixes #151

Related to the Agent-friendly parent roadmap (issue 136) only. This slice must not auto-close that parent.

🧪 Testing

  • Tests added/updated
  • PYTHONPATH=src pytest tests/skills/test_helper_contract.py tests/skills/test_memory_leak_contract.py tests/skills/test_memory_fragmentation_contract.py tests/skills/test_memory_peak_breakdown_contract.py tests/test_bundled_skills.py tests/skills/test_agent_e2e.py — 48 passed
  • python -m tests.skills validate tests/skills/suites/pt-snap-agent-e2e/suite.yaml
  • ruff check on edited test files
  • Full pytest suite
  • Manual testing completed

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    Snapshot provenance decision: no-update
    Snapshot provenance no-update reason: This PR only changes skill markdown, bundled copies, skill-eval cases/baselines, contract tests, and a changelog bullet. It does not modify src/pt_snap_cli/snapshot/**.

📋 Additional Notes

  • Also edits CHANGELOG.md under [0.4.0]. Parallel with the snapshot type-check PR; rebase the later merge on that file.
  • Skill copies under skills/ and src/pt_snap_cli/bundled_skills/ stay identical.

Focus can warn and exit 0 when the target file is gone, so agents treated
a sibling .db as free to inspect with sqlite. Require user confirmation
and pt-snap metadata first, without persisting focus or importing.

Fixes #151
@codeasier
codeasier merged commit 55f7511 into main Sep 23, 2026
6 checks passed
@codeasier
codeasier deleted the feat/issue-151-sibling-db-docs branch October 3, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS] pt-snap-helper / 诊断 skill 缺少 "focus 指向的 DB 不存在但存在 sibling DB" 的处理规则

1 participant