@codewizard-dt/bootstrap 2.10.0
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.
- package/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: bug-file
|
|
3
|
+
description: File a new bug report in wiki/work/bugs/ with required-on-report fields and append it to the bug index
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: <short bug description>
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md` + `wiki/work/bugs/lifecycle.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
# File Bug
|
|
13
|
+
|
|
14
|
+
Create a new bug file in `wiki/work/bugs/` with status `new`. Gather every required-on-report field before writing — a bug without reliable reproduction is a complaint, not a bug.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
**Input**: $ARGUMENTS
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Instructions
|
|
23
|
+
|
|
24
|
+
### Step 1: Read the Spec
|
|
25
|
+
|
|
26
|
+
Read `wiki/work/bugs/lifecycle.md` — the authoritative frontmatter schema (fields, allowed `severity` / `priority` values), status set, and close-gate/required-fields rules. The bug file's body structure and field definitions are specified inline in this skill (Steps 3–6).
|
|
27
|
+
|
|
28
|
+
### Step 2: Summarize the Reported Symptom
|
|
29
|
+
|
|
30
|
+
From `$ARGUMENTS`, extract:
|
|
31
|
+
- A short, symptom-focused title (not a suspected cause)
|
|
32
|
+
- Any reproduction steps, environment, or impact already mentioned
|
|
33
|
+
- Any severity hint ("crashes", "data loss", "cosmetic", etc.)
|
|
34
|
+
|
|
35
|
+
Hold these in working memory; do **not** invent details the user did not provide.
|
|
36
|
+
|
|
37
|
+
### Step 3: Gather Required Fields via Q&A
|
|
38
|
+
|
|
39
|
+
For each missing required-on-report field, use `AskUserQuestion`. Batch related questions into a single call where the UI permits. Required fields:
|
|
40
|
+
|
|
41
|
+
| Field | What to ask |
|
|
42
|
+
|-------|-------------|
|
|
43
|
+
| Title | Confirm or refine the short symptom title (if `$ARGUMENTS` was vague) |
|
|
44
|
+
| Severity | Single-select: `critical` / `high` / `medium` / `low` — the allowed values are defined in `wiki/work/bugs/lifecycle.md` |
|
|
45
|
+
| Reporter | Name or role (default: the current user from `git config user.name`) |
|
|
46
|
+
| Environment | OS / Platform, Browser or Runtime, App version or commit SHA, relevant config (feature flags, locale, account type) |
|
|
47
|
+
| Steps to Reproduce | Numbered list — block progress if reproduction is non-deterministic without recording `Reproducibility: rarely` or `once` with notes |
|
|
48
|
+
| Expected Behavior | One paragraph |
|
|
49
|
+
| Actual Behavior | Observed output only — error messages, stack traces, console output. No speculation. Offer to capture a screenshot path in `wiki/work/uat/screenshots/` if relevant |
|
|
50
|
+
| Reproducibility | Single-select: `always` / `sometimes` / `rarely` / `once`; plus `First seen` and `Last seen` dates |
|
|
51
|
+
|
|
52
|
+
**Do not** ask for `Priority`, `Assignee`, `Impact`, `Workaround`, `Tags`, `Linked task`, `Root Cause`, or `Resolution` — those belong to `/bug-triage` or `/bug-close`. Leaving them blank (or with the templated placeholder line) on initial filing is correct.
|
|
53
|
+
|
|
54
|
+
**Exception**: if the user mentions a task in `$ARGUMENTS`, accept it in either `TASK-NNN` or `[[TASK-NNN]]` form and normalize to `"[[TASK-NNN]]"` for the `linked_task:` frontmatter field. If no task is mentioned, set `linked_task: "—"`.
|
|
55
|
+
|
|
56
|
+
If the user cannot supply reliable Steps to Reproduce, STOP and tell them:
|
|
57
|
+
|
|
58
|
+
> Cannot file this bug yet — Steps to Reproduce are required. Capture a deterministic trigger first (a failing test, a screencast, a server log timestamp), then re-run `/bug-file`.
|
|
59
|
+
|
|
60
|
+
### Step 4: Determine the Next Bug Number
|
|
61
|
+
|
|
62
|
+
Scan **all** bug folders to find the next available 4-digit ID:
|
|
63
|
+
- `mcp__serena__list_dir` on `wiki/work/bugs/` and `wiki/work/bugs/archive/` (skip either that doesn't exist)
|
|
64
|
+
- Collect every `NNNN-` prefix; take `max + 1`; zero-pad to 4 digits.
|
|
65
|
+
- Also scan `wiki/work/bugs/index.md` for any reserved IDs not yet on disk.
|
|
66
|
+
- Never re-use a number — IDs are immutable references.
|
|
67
|
+
|
|
68
|
+
Derive the slug from the title: lowercase, hyphen-separated, 2–5 words, ≤ 60 chars. Describe the **symptom**, not the suspected cause (e.g., `login-fails-on-safari`, not `safari-cookie-handler-bug`).
|
|
69
|
+
|
|
70
|
+
### Step 5: Present and Confirm
|
|
71
|
+
|
|
72
|
+
Before writing, present:
|
|
73
|
+
- Resolved filename: `wiki/work/bugs/NNNN-<slug>.md`
|
|
74
|
+
- Title, Severity, Reporter
|
|
75
|
+
- The gathered Environment, Steps, Expected, Actual, Reproducibility values
|
|
76
|
+
|
|
77
|
+
Ask the user to confirm via `AskUserQuestion` ("File this bug? Yes / Edit / Cancel"). If `Cancel`, STOP. If `Edit`, ask which field and re-prompt.
|
|
78
|
+
|
|
79
|
+
### Step 6: Write the Bug File
|
|
80
|
+
|
|
81
|
+
Use `Write` to create `wiki/work/bugs/NNNN-<slug>.md`, following the frontmatter schema in `wiki/work/bugs/lifecycle.md` and the field set gathered in Steps 3–5. Set:
|
|
82
|
+
|
|
83
|
+
- `Status: new`
|
|
84
|
+
- `Priority: —` (filled in triage)
|
|
85
|
+
- `Assignee: —` (filled in triage)
|
|
86
|
+
- `Tags: —` (filled in triage)
|
|
87
|
+
- `linked_task:` — `"[[TASK-NNN]]"` if a task was mentioned (normalized from either `TASK-NNN` or `[[TASK-NNN]]` input); `"—"` otherwise
|
|
88
|
+
- `Reported`: today's date (`YYYY-MM-DD`)
|
|
89
|
+
- `Last updated`: today's date
|
|
90
|
+
- Leave `Root Cause Analysis`, `Resolution`, and `Related` sections present but empty (the templated placeholder line under each `>` quote is fine)
|
|
91
|
+
|
|
92
|
+
### Step 7: Update the Bug Index
|
|
93
|
+
|
|
94
|
+
Append a bullet line to `wiki/work/bugs/index.md` (active items only — a flat list, no table). Insert in numeric order. Entry format (documented at the top of `index.md`):
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
- [BUG-NNNN — <title>](BUG-NNNN-slug.md) — <one-line summary> · <status> · <priority>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`<status>` is the status you set in Step 6; `<priority>` is `—` until triage. If the index still shows the placeholder line (`_(none yet)_`), replace it with the new line.
|
|
101
|
+
|
|
102
|
+
Use **`Edit`** — one targeted call. Never `sed`, `awk`, `perl -i`, or `echo >>`. See `.docs/guides/mcp-tools.md`.
|
|
103
|
+
|
|
104
|
+
### Step 8: Report Completion
|
|
105
|
+
|
|
106
|
+
Print:
|
|
107
|
+
- Created file: `wiki/work/bugs/NNNN-<slug>.md`
|
|
108
|
+
- Bug ID: `BUG-NNNN`
|
|
109
|
+
- Status: `new`
|
|
110
|
+
- Next step:
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
To triage: /bug-triage BUG-NNNN
|
|
114
|
+
```
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: bug-triage
|
|
3
|
+
description: Triage an open bug — set priority/assignee/tags/impact, then keep it in wiki/work/bugs/, advance it to in-progress, or reject it (wontfix/duplicate/cannot-reproduce) and archive it
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: <BUG-NNNN, path, or number-slug>
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
# Triage Bug
|
|
13
|
+
|
|
14
|
+
Walk an existing bug through triage: confirm reproducibility, assign priority/assignee/tags, document impact, then decide the outcome. For active outcomes (triaged, in-progress) the file stays in `wiki/work/bugs/`. For terminal reject outcomes (wontfix, duplicate, cannot-reproduce) the file is moved to `wiki/work/bugs/archive/`.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
**Input**: $ARGUMENTS
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Instructions
|
|
23
|
+
|
|
24
|
+
### Step 1: Resolve the Bug File
|
|
25
|
+
|
|
26
|
+
Parse `$ARGUMENTS` to find the bug. Accepted forms:
|
|
27
|
+
- `BUG-NNNN` (e.g. `BUG-0042`)
|
|
28
|
+
- `NNNN` (e.g. `0042` or `42`)
|
|
29
|
+
- `NNNN-slug` (e.g. `0042-csv-export`)
|
|
30
|
+
- Full path (e.g. `wiki/work/bugs/BUG-0042-csv-export.md`)
|
|
31
|
+
|
|
32
|
+
Resolution order:
|
|
33
|
+
1. If full path: confirm with `mcp__serena__find_file`.
|
|
34
|
+
2. Otherwise normalize to a `BUG-NNNN*` pattern and search `wiki/work/bugs/` via `mcp__serena__find_file`.
|
|
35
|
+
3. If not found, STOP and report the error.
|
|
36
|
+
|
|
37
|
+
Read the bug file in full.
|
|
38
|
+
|
|
39
|
+
### Step 2: Re-triage Guard
|
|
40
|
+
|
|
41
|
+
Check the `status:` frontmatter field.
|
|
42
|
+
|
|
43
|
+
- If `status: open` or `status: triaged` → proceed.
|
|
44
|
+
- Any other status (`in-progress`, `closed`, `wontfix`, `duplicate`, `cannot-reproduce`) → STOP and tell the user: "BUG-NNNN has status `<status>` and cannot be re-triaged via this skill."
|
|
45
|
+
|
|
46
|
+
### Step 3: Audit Required-on-Report Fields
|
|
47
|
+
|
|
48
|
+
Before triaging, every required-on-report field must be present and non-templated:
|
|
49
|
+
|
|
50
|
+
- Severity, Reporter, Reported date
|
|
51
|
+
- Environment (all sub-fields filled with real values, not `<…>` placeholders)
|
|
52
|
+
- Steps to Reproduce (numbered, deterministic enough for another engineer)
|
|
53
|
+
- Expected Behavior, Actual Behavior
|
|
54
|
+
- Reproducibility (`always` / `sometimes` / `rarely` / `once` + dates)
|
|
55
|
+
|
|
56
|
+
If any field is missing or still has a templated placeholder, list them and ask the user to fill them in via `AskUserQuestion`. Update the file with `Edit` before proceeding.
|
|
57
|
+
|
|
58
|
+
### Step 4: Gather Triage Fields
|
|
59
|
+
|
|
60
|
+
For each triage field, use `AskUserQuestion`:
|
|
61
|
+
|
|
62
|
+
| Field | Question form |
|
|
63
|
+
|-------|---------------|
|
|
64
|
+
| Priority | Single-select: `P0` / `P1` / `P2` / `P3` |
|
|
65
|
+
| Severity (confirm) | Re-confirm or revise the reporter-set severity |
|
|
66
|
+
| Assignee | Free-text (name or role); `—` for backlog |
|
|
67
|
+
| Tags | Free-text comma-separated areas (e.g. `auth, frontend`) |
|
|
68
|
+
| Impact | Free-text — who is affected, how many, what does it block |
|
|
69
|
+
| Workaround | Free-text; `None known` is a valid answer |
|
|
70
|
+
|
|
71
|
+
### Step 5: Decide the Outcome
|
|
72
|
+
|
|
73
|
+
Use `AskUserQuestion` (single-select) to pick one of three outcomes:
|
|
74
|
+
|
|
75
|
+
| Choice | Status flip | Index row | When to pick |
|
|
76
|
+
|--------|-------------|-----------|--------------|
|
|
77
|
+
| **Start work now** | `open`/`triaged` → `in-progress` | STAYS — update status text | Assignee is starting immediately |
|
|
78
|
+
| **Defer / keep triaged** | `open` → `triaged` | STAYS — update status text | Backlog or scheduled for a later iteration |
|
|
79
|
+
| **Reject** (wontfix / duplicate / cannot-reproduce) | → `wontfix` \| `duplicate` \| `cannot-reproduce` | REMOVE row | Deliberate rejection decision |
|
|
80
|
+
|
|
81
|
+
For reject outcomes, require supporting information before proceeding:
|
|
82
|
+
- `wontfix` → rationale + decider captured in `## Resolution`
|
|
83
|
+
- `duplicate` → canonical `BUG-NNNN` recorded under `## Related → Duplicate of:`
|
|
84
|
+
- `cannot-reproduce` → what was attempted, logged in `## Resolution`
|
|
85
|
+
|
|
86
|
+
If the required field is absent, ask via `AskUserQuestion` and refuse to proceed until filled.
|
|
87
|
+
|
|
88
|
+
### Step 6: Apply Updates
|
|
89
|
+
|
|
90
|
+
Edit the bug file using `Edit` (never `sed`/`echo`/`awk`):
|
|
91
|
+
|
|
92
|
+
1. Flip `status:` to the new value.
|
|
93
|
+
2. Set `priority:`, `assignee:`, `tags:`, `impact:`, `workaround:` as gathered.
|
|
94
|
+
3. For reject outcomes, fill the required field(s) in `## Resolution` or `## Related`.
|
|
95
|
+
4. Bump `updated:` to today's date (`YYYY-MM-DD`).
|
|
96
|
+
|
|
97
|
+
### Step 7: Update the Bug Index
|
|
98
|
+
|
|
99
|
+
Read `wiki/work/bugs/index.md`. Apply changes with `Edit`:
|
|
100
|
+
|
|
101
|
+
- **Start work / Defer**: find the row for this bug and update the `Status` column text. Do not move the file.
|
|
102
|
+
- **Reject**: remove the entire row from the active index. Then run the archive-move sequence (Step 7a below).
|
|
103
|
+
|
|
104
|
+
#### Step 7a: Archive-Move for Reject Outcomes
|
|
105
|
+
|
|
106
|
+
For `wontfix`, `duplicate`, and `cannot-reproduce` outcomes only (`Bash` only for `git mv`):
|
|
107
|
+
|
|
108
|
+
1. `Bash`: `git mv wiki/work/bugs/NNNN-slug.md wiki/work/bugs/archive/NNNN-slug.md`
|
|
109
|
+
2. `Edit`: (active index row already removed in Step 7 above)
|
|
110
|
+
3. `Edit`: append to `wiki/work/bugs/archive/index.md`: `| [[BUG-NNNN]] | <title> | <status> | YYYY-MM-DD |`
|
|
111
|
+
4. `Edit`: append to `wiki/log.md`
|
|
112
|
+
|
|
113
|
+
For active outcomes (Start work / Defer), skip this step entirely — the file stays at `wiki/work/bugs/NNNN-slug.md`.
|
|
114
|
+
|
|
115
|
+
### Step 8: Cross-Linking
|
|
116
|
+
|
|
117
|
+
- If outcome is **Duplicate**: open the canonical bug file and append a line to its `## Related → Related bugs:` section listing this bug ID. Use `Edit`.
|
|
118
|
+
- If outcome is **Start work now**: ask whether to spawn a fix task via `/task-add`. If yes, suggest the command — do not invoke it automatically.
|
|
119
|
+
|
|
120
|
+
### Step 9: Append Log Entry
|
|
121
|
+
|
|
122
|
+
Append to `wiki/log.md`:
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
## [YYYY-MM-DD] bug-triage | BUG-NNNN <title>
|
|
126
|
+
Triaged: status → <new-status>. <one sentence summary of decision>.
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Use `Edit` (append to end of file).
|
|
130
|
+
|
|
131
|
+
### Step 10: Report Completion
|
|
132
|
+
|
|
133
|
+
Print:
|
|
134
|
+
- Bug ID and title
|
|
135
|
+
- Old status → new status
|
|
136
|
+
- Index row action (updated / removed)
|
|
137
|
+
- File location (unchanged for active outcomes; moved to `archive/` for reject outcomes)
|
|
138
|
+
- Suggested next step:
|
|
139
|
+
- Start work / Defer → `/bug-close BUG-NNNN` when the fix is merged and verified
|
|
140
|
+
- Reject outcomes → terminal; file archived at `wiki/work/bugs/archive/BUG-NNNN-slug.md` (recoverable via git history)
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: company-align
|
|
3
|
+
description: Analyse project–company fit — maps project implementation, style, and functionality against company mission, values, and likely needs; surfaces gaps and strengths
|
|
4
|
+
category: researching
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
effort: high
|
|
7
|
+
argument-hint: [company-slug]
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Company Align
|
|
13
|
+
|
|
14
|
+
Analyse how well this project aligns with a researched company. Read all company context files from `raw/companies/`, perform a deep read of the project, then produce a structured alignment report covering mission fit, technical fit, functional gaps, and style alignment.
|
|
15
|
+
|
|
16
|
+
Output is written to `raw/companies/<slug>/alignment.md`.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
**Company slug (optional)**: $ARGUMENTS
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Phase 1: Resolve Target Company
|
|
25
|
+
|
|
26
|
+
1. Use `mcp__serena__list_dir` on `raw/companies/` to discover available company slugs
|
|
27
|
+
2. **If `$ARGUMENTS` is non-empty**: use it as the slug directly
|
|
28
|
+
3. **If `$ARGUMENTS` is empty and exactly one company exists**: use that company
|
|
29
|
+
4. **If `$ARGUMENTS` is empty and multiple companies exist**: list the available slugs and ask the user which one to align against, then stop and wait
|
|
30
|
+
5. Confirm the slug, then read **every file** in `raw/companies/<slug>/` using `mcp__serena__list_dir` + Read:
|
|
31
|
+
- `index.md`, `overview.md`, `leadership.md`, `news.md`, `competitive.md`, `culture.md` (if present)
|
|
32
|
+
- Any other `.md` files present (e.g. a prior `alignment.md` — note it exists but proceed to overwrite)
|
|
33
|
+
|
|
34
|
+
Build an internal **Company Context** object from these files capturing:
|
|
35
|
+
- Mission / values / value proposition
|
|
36
|
+
- Products, customers, market segment
|
|
37
|
+
- Business model and revenue drivers
|
|
38
|
+
- Tech stack and engineering culture (if known)
|
|
39
|
+
- Recent strategic priorities and news signals
|
|
40
|
+
- Competitive pressures and differentiators
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Phase 2: Project Analysis
|
|
45
|
+
|
|
46
|
+
Use Serena to build a complete picture of this project. Do NOT use Bash, Read, Grep, or Glob on code files.
|
|
47
|
+
|
|
48
|
+
### 2a. Structure & Architecture
|
|
49
|
+
- `mcp__serena__list_dir(".", recursive=true)` — overall directory shape
|
|
50
|
+
- `mcp__serena__get_symbols_overview` on key source directories — modules, classes, entry points
|
|
51
|
+
- Identify: project type (web app / API / CLI / library / data pipeline / etc.), primary language(s), frameworks
|
|
52
|
+
|
|
53
|
+
### 2b. Functionality — What Does This Project Do?
|
|
54
|
+
- Read README, `package.json` / `pyproject.toml` / equivalent for declared purpose and scripts
|
|
55
|
+
- `mcp__serena__get_symbols_overview` on main source files to enumerate features and capabilities
|
|
56
|
+
- Check `wiki/work/tasks/`, `wiki/work/requirements/`, `wiki/work/roadmaps/` for declared scope and in-progress work
|
|
57
|
+
- Summarise: core features, key user flows, integrations, APIs exposed or consumed
|
|
58
|
+
|
|
59
|
+
### 2c. Technical Style & Quality Signals
|
|
60
|
+
- Identify: coding conventions, test coverage presence, CI/CD setup, linting/type-checking, documentation quality
|
|
61
|
+
- Note: patterns used (DDD, hexagonal, REST, event-driven, etc.), dependency choices, any AI/LLM integrations
|
|
62
|
+
- Check for: accessibility, internationalisation, security practices, observability (logging, metrics, tracing)
|
|
63
|
+
|
|
64
|
+
### 2d. Project Maturity & Completeness
|
|
65
|
+
- What is clearly production-ready vs. prototype/scaffold?
|
|
66
|
+
- Are there obvious TODOs, stub implementations, or known gaps in `wiki/work/bugs/` or task backlogs?
|
|
67
|
+
- What is the deployment story (Docker, cloud, serverless, etc.)?
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Phase 3: Alignment Analysis
|
|
72
|
+
|
|
73
|
+
With both the Company Context (Phase 1) and Project Analysis (Phase 2) in hand, perform the following structured assessments.
|
|
74
|
+
|
|
75
|
+
### 3a. Mission & Values Alignment
|
|
76
|
+
For each of the company's stated values or mission pillars, assess how the project demonstrates (or fails to demonstrate) that value:
|
|
77
|
+
|
|
78
|
+
| Company Value / Mission Pillar | Evidence in Project | Alignment | Notes |
|
|
79
|
+
|-------------------------------|--------------------:|:---------:|-------|
|
|
80
|
+
| <value> | <what shows it> | Strong / Partial / Weak / None | |
|
|
81
|
+
|
|
82
|
+
Score: **Strong** = concrete, visible implementation. **Partial** = present but underdeveloped. **Weak** = implicit or aspirational only. **None** = no evidence.
|
|
83
|
+
|
|
84
|
+
### 3b. Technical Fit
|
|
85
|
+
Does the project's tech stack, architecture, and engineering practices align with what is known about the company's engineering culture and preferences?
|
|
86
|
+
|
|
87
|
+
- Stack overlap (languages, frameworks, cloud platforms)
|
|
88
|
+
- Engineering practices match (testing rigour, CI/CD maturity, code style)
|
|
89
|
+
- Scalability / reliability posture vs. company's product scale
|
|
90
|
+
- Any tech the company is known to use that is notably absent
|
|
91
|
+
|
|
92
|
+
### 3c. Functional Fit — What Does the Company Likely Need?
|
|
93
|
+
Based on the company's products, customers, strategic priorities, and recent news, infer the types of problems or capabilities they likely value. Then map the project's functionality against these:
|
|
94
|
+
|
|
95
|
+
| Inferred Company Need | Project Capability | Gap Level | Notes |
|
|
96
|
+
|----------------------|-------------------|:---------:|-------|
|
|
97
|
+
| <need> | <what project does> | None / Minor / Major / Missing | |
|
|
98
|
+
|
|
99
|
+
**Gap Level**: **None** = project covers it well. **Minor** = partial coverage, easy to extend. **Major** = present but shallow or different approach needed. **Missing** = no coverage at all.
|
|
100
|
+
|
|
101
|
+
### 3d. Style & Presentation Alignment
|
|
102
|
+
- Does the project's README, documentation, and code organisation reflect the professionalism expected?
|
|
103
|
+
- Does the project's domain or problem space resonate with the company's industry or customer base?
|
|
104
|
+
- Would a senior engineer at this company find the codebase immediately legible and idiomatic?
|
|
105
|
+
- Tone of documentation vs. company's public communication style
|
|
106
|
+
|
|
107
|
+
### 3e. Differentiating Strengths
|
|
108
|
+
What does the project do *especially well* that the company would likely find impressive or immediately useful? List 3–5 specific, concrete strengths with evidence.
|
|
109
|
+
|
|
110
|
+
### 3f. Actionable Gaps
|
|
111
|
+
What are the highest-value improvements that would most increase alignment with this company? Rank by impact:
|
|
112
|
+
|
|
113
|
+
| Priority | Gap | Effort | Suggested Fix |
|
|
114
|
+
|----------|-----|:------:|---------------|
|
|
115
|
+
| 1 | | Low/Med/High | |
|
|
116
|
+
| 2 | | | |
|
|
117
|
+
| ... | | | |
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Phase 4: Write Output
|
|
122
|
+
|
|
123
|
+
**Never overwrite an existing `raw/` file.** Writing new files into `raw/` is allowed, but if the target path already exists, write to the next free numeric sibling instead — `alignment-2.md`, then `alignment-3.md`, and so on. The existing file is immutable ground truth; leave it untouched. **The new `-N` file must not repeat data already present in the prior file(s)** — read the existing file(s) first and capture only what is new, changed, or contradicts the prior analysis, cross-referencing the existing file for everything unchanged (e.g. `> Unchanged since [alignment.md](alignment.md); this delta covers …`).
|
|
124
|
+
|
|
125
|
+
Write `raw/companies/<slug>/alignment.md` (or the next free `alignment-N.md`) with the following structure:
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
---
|
|
129
|
+
company: <Company Name>
|
|
130
|
+
slug: <slug>
|
|
131
|
+
analysed: <YYYY-MM-DD>
|
|
132
|
+
overall-alignment: <Strong / Moderate / Weak>
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
# <Company Name> — Project Alignment Report
|
|
136
|
+
|
|
137
|
+
> **Overall alignment: <Strong / Moderate / Weak>**
|
|
138
|
+
> <One sentence verdict.>
|
|
139
|
+
|
|
140
|
+
## Mission & Values Fit
|
|
141
|
+
|
|
142
|
+
<table from 3a>
|
|
143
|
+
|
|
144
|
+
**Summary**: <2–3 sentences on how well the project embodies the company's mission>
|
|
145
|
+
|
|
146
|
+
## Technical Fit
|
|
147
|
+
|
|
148
|
+
<narrative + bullet points from 3b>
|
|
149
|
+
|
|
150
|
+
## Functional Fit & Gaps
|
|
151
|
+
|
|
152
|
+
<table from 3c>
|
|
153
|
+
|
|
154
|
+
**Summary**: <2–3 sentences on coverage>
|
|
155
|
+
|
|
156
|
+
## Style & Presentation
|
|
157
|
+
|
|
158
|
+
<narrative from 3d>
|
|
159
|
+
|
|
160
|
+
## Differentiating Strengths
|
|
161
|
+
|
|
162
|
+
1. **<Strength>**: <evidence>
|
|
163
|
+
2. ...
|
|
164
|
+
|
|
165
|
+
## Actionable Gaps (ranked by impact)
|
|
166
|
+
|
|
167
|
+
<table from 3f>
|
|
168
|
+
|
|
169
|
+
## Suggested Talking Points
|
|
170
|
+
|
|
171
|
+
Based on the alignment above, these are the strongest angles to emphasise when presenting this project to <Company Name>:
|
|
172
|
+
|
|
173
|
+
1. ...
|
|
174
|
+
2. ...
|
|
175
|
+
3. ...
|
|
176
|
+
|
|
177
|
+
## Suggested Improvements Before Presenting
|
|
178
|
+
|
|
179
|
+
If time permits before engaging with <Company Name>, these changes would meaningfully increase alignment:
|
|
180
|
+
|
|
181
|
+
- [ ] <improvement> — <why it matters to this company>
|
|
182
|
+
- [ ] ...
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Phase 5: Report to User
|
|
188
|
+
|
|
189
|
+
After writing the file, tell the user:
|
|
190
|
+
- The path written: `raw/companies/<slug>/alignment.md`
|
|
191
|
+
- Overall alignment verdict and one-sentence rationale
|
|
192
|
+
- Top 3 strengths and top 3 gaps (brief, scannable)
|
|
193
|
+
- Suggest: "Run `/company-align <other-slug>` to compare against another company" if multiple companies exist in `raw/companies/`
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## CRITICAL Rules
|
|
198
|
+
|
|
199
|
+
1. **Serena for all code navigation** — no Bash `ls`/`cat`/`grep`, no Read on code files
|
|
200
|
+
2. **Ground every claim in evidence** — cite specific files, symbols, or company context sources; no speculation presented as fact
|
|
201
|
+
3. **Distinguish project reality from roadmap intentions** — what exists in code now vs. what is planned
|
|
202
|
+
4. **Be direct about weaknesses** — a gap listed honestly is more useful than an inflated alignment score
|
|
203
|
+
5. **No Brave Search in this skill** — all company data comes from the already-researched context files; do not re-search
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: debug-logs
|
|
3
|
+
description: Diagnose points of failure by inspecting session context, running processes, and conventional log stores; produce a ranked list of likely causes and next actions without applying fixes
|
|
4
|
+
category: researching
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: "[optional symptom or error message]"
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
# Debug
|
|
13
|
+
|
|
14
|
+
Diagnose a failure by gathering session context, locating the right log stores, and producing a ranked list of likely causes with concrete next actions. **Read-only by default** — propose fixes, do not apply them.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
**Symptom (optional)**: $ARGUMENTS
|
|
19
|
+
|
|
20
|
+
If `$ARGUMENTS` is empty, infer the failure from the most recent failed command, error message, or the user's stated frustration in the conversation. If nothing is obvious, ask one focused clarifying question before continuing.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Phase 1: Capture Session Context
|
|
25
|
+
|
|
26
|
+
Build a picture of *what was being attempted* before triaging logs.
|
|
27
|
+
|
|
28
|
+
1. **Recent intent** — restate, in one sentence, what the user was trying to accomplish (from `$ARGUMENTS` and recent turns).
|
|
29
|
+
2. **Recent edits** — run `git status` and `git diff` (and `git log -5 --oneline`) to see what changed in the working tree. The failure is almost always related to the most recent diff.
|
|
30
|
+
3. **Background processes** — call `TaskList` to find any dev servers, watchers, test runners, or build processes spawned in this session. Note their IDs.
|
|
31
|
+
4. **Foreground errors** — scan the conversation for recent failed Bash exits, stack traces, hook rejections, or non-zero return codes. Quote the exact error if available.
|
|
32
|
+
5. **Project memories** — `mcp__serena__list_memories(topic="<failure area>")` then read any memory describing known gotchas or prior incidents in this area.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Phase 2: Identify Relevant Log Stores
|
|
37
|
+
|
|
38
|
+
Pick the smallest set of sources that could contain the failure signal. Do not dump every log; pick by symptom.
|
|
39
|
+
|
|
40
|
+
| Symptom shape | Likely log source | Tool |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| Background server crashed / 500s | `TaskOutput` on the dev server task | `TaskOutput` |
|
|
43
|
+
| Test failure / assertion error | `TaskOutput` on the test task, or rerun with `--reporter=verbose` | `TaskOutput`, `Bash` |
|
|
44
|
+
| Build / compile error | Build task output, `tsc` / `next build` cache, `.next/trace` | `TaskOutput`, `Read` |
|
|
45
|
+
| Browser-side failure (UI bug, console error) | Playwright snapshot + screenshot | `mcp__playwright__browser_snapshot`, `mcp__playwright__browser_take_screenshot` |
|
|
46
|
+
| Type / lint regression | IDE diagnostics | `mcp__ide__getDiagnostics` |
|
|
47
|
+
| CI failure on a PR/branch | GitHub Actions logs | `gh run list`, `gh run view --log-failed` |
|
|
48
|
+
| Deployed app failure (DigitalOcean) | App platform logs | `mcp__digitalocean__apps-get-logs` |
|
|
49
|
+
| Application file logs | `./logs/`, `./tmp/`, `./.next/`, `./dist/`, `~/Library/Logs/<app>/` | `mcp__serena__list_dir`, `Read` |
|
|
50
|
+
| Database / migration | DB cluster logs (managed) or local pg/mysql log path | `mcp__digitalocean__db-cluster-*`, `Read` |
|
|
51
|
+
|
|
52
|
+
**Discovery rules:**
|
|
53
|
+
- Use `mcp__serena__list_dir` to find log directories — never `ls`, `find`, or `tail` via shell for exploration.
|
|
54
|
+
- Use `Read` (with `offset`/`limit`) to read the **tail** of large log files, not `cat` / `tail -f`.
|
|
55
|
+
- For background process output, prefer `TaskOutput` (it streams the running process) over re-spawning the command.
|
|
56
|
+
- If a relevant log source is unreachable (no permission, no MCP available, file missing), say so explicitly and move on.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Phase 3: Inspect & Extract
|
|
61
|
+
|
|
62
|
+
For each selected source:
|
|
63
|
+
|
|
64
|
+
1. **Read the most recent slice** — last ~200 lines is usually enough; expand only if the stack trace is truncated.
|
|
65
|
+
2. **Extract the failure signal** — quote the actual error message, exception type, file/line, HTTP status, exit code. Skip ambient log noise.
|
|
66
|
+
3. **Note the timestamp** — confirm the error occurred *after* the most recent edit (Phase 1, step 2). If it predates the edit, the failure may be unrelated to current work.
|
|
67
|
+
4. **Cross-reference** — when an error names a file/symbol, use `mcp__serena__find_symbol` to read the current implementation and look for a mismatch with the error.
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Phase 4: Correlate & Hypothesize
|
|
72
|
+
|
|
73
|
+
Produce a ranked list of likely causes. Be concrete — name files, lines, and symbols.
|
|
74
|
+
|
|
75
|
+
For each hypothesis, capture:
|
|
76
|
+
|
|
77
|
+
- **Cause** (one sentence)
|
|
78
|
+
- **Evidence** (which log line + which code location point to it)
|
|
79
|
+
- **Confidence** (high / medium / low — be honest about guessing)
|
|
80
|
+
- **Next action** (a specific command, edit, or further check the user can run)
|
|
81
|
+
|
|
82
|
+
Stop at 3 hypotheses unless the user asked for an exhaustive list. Order by confidence, then by cheapness-to-verify.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Phase 5: Report
|
|
87
|
+
|
|
88
|
+
Present the diagnosis as a short structured report:
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
### Symptom
|
|
92
|
+
<one line>
|
|
93
|
+
|
|
94
|
+
### What changed recently
|
|
95
|
+
<git diff summary, 1-3 lines>
|
|
96
|
+
|
|
97
|
+
### Logs inspected
|
|
98
|
+
- <source 1>: <key finding>
|
|
99
|
+
- <source 2>: <key finding>
|
|
100
|
+
|
|
101
|
+
### Ranked hypotheses
|
|
102
|
+
1. **<cause>** — <evidence> [confidence: H/M/L]
|
|
103
|
+
→ next: <action>
|
|
104
|
+
2. ...
|
|
105
|
+
|
|
106
|
+
### Recommended next step
|
|
107
|
+
<one concrete action — usually "run X" or "let me try the fix in <file>:<line>">
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
After reporting, **stop and wait for direction**. Do not auto-apply a fix unless the user explicitly says to. If the user confirms a fix path, hand off to standard editing tools (Serena symbolic / Edit) — debugging itself remains read-only.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## When Findings Are Novel
|
|
115
|
+
|
|
116
|
+
If diagnosis surfaced a non-obvious failure mode that future sessions would benefit from (e.g. "this error always means env var X is unset", "this stack trace is always a stale build cache"), suggest writing a Serena memory under `gotchas/<area>/<short-name>` — but only with user approval. Do not write the memory unprompted.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## CRITICAL Rules
|
|
121
|
+
|
|
122
|
+
1. **Read-only by default** — debug investigates; the user decides whether to fix.
|
|
123
|
+
2. **Pick log sources by symptom** — do not enumerate every log store on every invocation.
|
|
124
|
+
3. **Tail, do not dump** — use `Read` with `offset`/`limit`; never spawn `tail -f` blocking processes.
|
|
125
|
+
4. **Never spawn new long-running processes** to gather logs. Read what is already there or use existing background tasks via `TaskOutput`.
|
|
126
|
+
5. **Quote actual error text** — paraphrased errors hide the real signal.
|
|
127
|
+
6. **Acknowledge gaps** — if a log source is missing or unreachable, say so; do not invent a hypothesis to fill the gap.
|
|
128
|
+
7. **Maximum 3 sub-processes at a time** if delegating parallel log reads.
|
|
129
|
+
8. **Always terminate** any process you started for diagnosis before reporting.
|