@pourkit/cli 0.0.0-next-20260708233839 → 0.0.0-next-20260709181702
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -45,12 +45,15 @@ Use this structure for `explore-codebase` answers. Omit empty sections, but keep
|
|
|
45
45
|
|
|
46
46
|
## Saved Research Metadata
|
|
47
47
|
|
|
48
|
-
When the user explicitly asks to save research, write it to `.pourkit/research/codebase/<YYYY-MM-DD>-<topic>.md` and start with:
|
|
48
|
+
When the user explicitly asks to save research, write it to `.pourkit/research/codebase/<domain>/<YYYY-MM-DD>-<topic>.md` and start with:
|
|
49
49
|
|
|
50
50
|
```md
|
|
51
51
|
# Codebase Navigation Atlas: <topic>
|
|
52
52
|
|
|
53
53
|
- Date: <YYYY-MM-DD>
|
|
54
|
+
- Last verified: <YYYY-MM-DD>
|
|
55
|
+
- Domain: <domain-slug>
|
|
56
|
+
- Research shape: Domain-specific | Domain-discovery
|
|
54
57
|
- Requested by: <user or session context if known>
|
|
55
58
|
- Source priority: current source > canonical Pourkit docs > plans/handoffs > ICM > web
|
|
56
59
|
- ICM recall: <command used or skipped reason>
|
|
@@ -58,4 +61,4 @@ When the user explicitly asks to save research, write it to `.pourkit/research/c
|
|
|
58
61
|
- Canonical docs update: Not performed unless explicitly confirmed
|
|
59
62
|
```
|
|
60
63
|
|
|
61
|
-
Saved research must remain navigation evidence. It does not create official subsystem vocabulary or architecture decisions by itself.
|
|
64
|
+
Saved research must remain navigation evidence. It does not create official subsystem vocabulary or architecture decisions by itself. If later code changes use the research and change the described system or subsystem, update the affected domain research file or clearly mark stale sections.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: explore-codebase
|
|
3
|
-
description:
|
|
3
|
+
description: Research codebases and produce a Codebase Navigation Atlas for domain discovery, feature/module ownership, entry points, tests, related docs, and undocumented repo navigation. Use when the user asks to research, explore, crawl, survey, understand, map, find a feature, locate a module, identify domain ownership, understand tests, navigate a large codebase, or investigate an undocumented repo.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Explore Codebase
|
|
@@ -9,6 +9,17 @@ Use this skill as a read-only research coordinator. Your job is to help the user
|
|
|
9
9
|
|
|
10
10
|
Default output is an in-chat **Codebase Navigation Atlas**. Do not write files by default.
|
|
11
11
|
|
|
12
|
+
## Research Routing
|
|
13
|
+
|
|
14
|
+
Treat research-oriented codebase queries as triggers even when the user does not say "explore". Before choosing implementation, review, or refactor workflows, check whether the ask is primarily to research, investigate, understand, map, crawl, survey, or locate code/domain behavior.
|
|
15
|
+
|
|
16
|
+
Scope each exploration as one of two research shapes:
|
|
17
|
+
|
|
18
|
+
- Domain-specific research: the prompt names or implies the domain to study, such as `featureA`, `featureB`, `pathfinding`, or `bounty-hunting`.
|
|
19
|
+
- Domain-discovery research: the prompt asks you to search, crawl, or survey the repository to identify which domains exist or which domain owns behavior.
|
|
20
|
+
|
|
21
|
+
Prefer the user's domain language for headings, saved paths, and atlas topic names. When the prompt does not provide a domain, discover candidate domains from source paths, tests, docs, and naming patterns before choosing a saved domain directory or presenting the atlas.
|
|
22
|
+
|
|
12
23
|
## Source Priority
|
|
13
24
|
|
|
14
25
|
Trust sources in this order:
|
|
@@ -80,8 +91,12 @@ Always include:
|
|
|
80
91
|
|
|
81
92
|
Only save durable research when the user explicitly asks to save it. Use:
|
|
82
93
|
|
|
83
|
-
`.pourkit/research/codebase/<YYYY-MM-DD>-<topic>.md`
|
|
94
|
+
`.pourkit/research/codebase/<domain>/<YYYY-MM-DD>-<topic>.md`
|
|
95
|
+
|
|
96
|
+
Use a prompt-provided domain slug when available. For domain-discovery research, use a discovered domain slug once evidence supports it, or `domain-discovery` while the output is still a cross-domain survey. Do not write saved research files directly under `.pourkit/research/codebase/`.
|
|
97
|
+
|
|
98
|
+
Saved research is a durable navigation artifact, not canonical architecture. Include metadata, domain, topic, evidence, confidence, open questions, last verified date, and links to source paths. Do not store durable research under `.pourkit/.tmp`.
|
|
84
99
|
|
|
85
|
-
Saved research is
|
|
100
|
+
Saved research is subject to change. If later implementation or refactor work uses saved research and changes the system or subsystem it describes, update the affected `.pourkit/research/codebase/<domain>/` research files in the same follow-up work so they match current source, or explicitly mark stale sections when certainty is low.
|
|
86
101
|
|
|
87
102
|
Canonical docs updates are separate work. Ask for explicit confirmation before editing `.pourkit/CONTEXT.md`, ADRs, or stable architecture docs.
|