avibebuilder/claude-prime / .claude/skills/diagnose
diagnose
VerifiedInvestigate unexpected behavior and mysterious bugs. Use when the cause of a problem is unknown and the user needs to understand WHY something is happening — symptoms like: sudden unexplained changes in metrics or behavior, works locally but not in staging/production, inconsistent or intermittent failures, correct code producing wrong results, operations succeeding but having no effect, environment-specific failures, duplicate executions, stale data, or any "why did this change?" or "why is this happening?" situation. Covers infrastructure anomalies (cache hit rates dropping, latency spikes, queue behavior shifts) as well as code bugs. The key signal is confusion about root cause, not a request to implement a known fix. Do NOT use for feature requests, known fixes, planning, or documentation tasks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.6 KB |
| references/runtime-debugging.md | markdown | 4.3 KB |
| scripts/__tests__/diagnose-server.test.js | script | 8.3 KB |
| scripts/diagnose-server.js | script | 2.0 KB |
| scripts/package.json | manifest | 175 B |
scripts/__tests__/diagnose-server.test.js
View on GitHub// Run with: node --test __tests__/diagnose-server.test.js
import { describe, it, before, after } from 'node:test';
import assert from 'node:assert';
import { spawn } from 'node:child_process';
import { readFileSync, existsSync, rmSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { request } from 'node:http';
const __dirname = fileURLToPath(new URL('.', import.meta.url));
const SERVER_PATH = join(__dirname, '..', 'diagnose-server.js');
const PORT = 6143;
const BASE_URL = `http://127.0.0.1:${PORT}`;
function startServer(cwd, sessionArg) {
const args = [SERVER_PATH];
if (sessionArg) args.push(sessionArg);
return spawn(process.execPath, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
}
function waitForReady(proc) {
return new Promise((resolve, reject) => {
let stdout = '';
const timeout = setTimeout(() => reject(new Error('Server start timeout')), 5000);
proc.stdout.on('data', (chunk) => {
stdout += chunk.toString();
try {
const parsed = JSON.parse(stdout.trim());
clearTimeout(timeout);
resolve(parsed);
} catch {}
});
proc.on('error', (err) => { clearTimeout(timeout); reject(err); });
proc.on('exit', (code) => {
if (code !== 0) { clearTimeout(timeout); reject(new Error(`Server exited with code ${code}`)); }
});
});
}
function httpRequest(method, path, body) {
return new Promise((resolve, reject) => {
const url = new URL(path, BASE_URL);
const opts = { method, hostname: url.hostname, port: url.port, path: url.pathname };
if (body !== undefined) opts.headers = { 'Content-Type': 'application/json' };
const req = request(opts, (res) => {
let data = '';
res.on('data', (c) => { data += c; });
res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: data }));
});
req.on('error', reject);
if (body !== undefined) req.write(typeof body === 'string' ? body : JSON.stringify(body));
req.end();
});
}
function killServer(proc) {
return new Promise((resolve) => {
if (!proc || proc.killed) return resolve();
proc.on('exit', resolve);
proc.kill('SIGTERM');
setTimeout(() => { if (!proc.killed) proc.kill('SIGKILL'); }, 2000);
});
}
describe('diagnose-server', () => {
let tmpDir;
before(() => {
tmpDir = join('/tmp', `diagnose-server-test-${Date.now()}`);
mkdirSync(tmpDir, { recursive: true });
});
after(() => {
rmSync(tmpDir, { recursive: true, force: true });
});
describe('Server starts and outputs JSON', () => {
let proc;
after(async () => { await killServer(proc); });
it('should output JSON with port, logFile, and sessionId on startup', async () => {
proc = startServer(tmpDir);
const output = await waitForReady(proc);
assert.strictEqual(output.port, PORT);
assert.ok(typeof output.logFile === 'string');
assert.ok(output.logFile.length > 0);
assert.ok(typeof output.sessionId === 'string');
assert.ok(output.sessionId.length > 0);
});
});
describe('POST /ingest/:sessionId', () => {
let proc;
let serverInfo;
before(async () => {
proc = startServer(tmpDir);
serverInfo = await waitForReady(proc);
});
after(async () => { await killServer(proc); });
it('should return 200 with { ok: true } for valid JSON payload', async () => {
const res = await httpRequest('POST', `/ingest/${serverInfo.sessionId}`, { level: 'info', msg: 'test' });
assert.strictEqual(res.status, 200);
const body = JSON.parse(res.body);
assert.strictEqual(body.ok, true);
});
});
describe('Log file creation', () => {
let proc;
let serverInfo;
const sid = `logtest-${Date.now()}`;
before(async () => {
proc = startServer(tmpDir, sid);
serverInfo = await waitForReady(proc);
});
after(async () => { await killServer(proc); });
it('should create a JSONL log file with _session and _ts fields', async () => {
const payload = { level: 'error', msg: 'something broke' };
await httpRequest('POST', `/ingest/${sid}`, payload);
assert.ok(existsSync(serverInfo.logFile), 'Log file should exist');
const lines = readFileSync(serverInfo.logFile, 'utf-8').trim().split('\n');
assert.strictEqual(lines.length, 1);
const entry = JSON.parse(lines[0]);
assert.strictEqual(entry.level, 'error');
assert.strictEqual(entry.msg, 'something broke');
assert.strictEqual(entry._session, sid);
assert.ok(typeof entry._ts === 'number');
});
});
describe('CORS headers', () => {
let proc;
before(async () => {
proc = startServer(tmpDir);
await waitForReady(proc);
});
after(async () => { await killServer(proc); });
it('should include Access-Control-Allow-Origin: * on responses', async () => {
const res = await httpRequest('POST', '/ingest/cors-test', { data: 1 });
assert.strictEqual(res.headers['access-control-allow-origin'], '*');
});
});
describe('OPTIONS preflight', () => {
let proc;
before(async () => {
proc = startServer(tmpDir);
await waitForReady(proc);
});
after(async () => { await killServer(proc); });
it('should return 204 with CORS headers', async () => {
const res = await httpRequest('OPTIONS', '/ingest/preflight');
assert.strictEqual(res.status, 204);
assert.strictEqual(res.headers['access-control-allow-origin'], '*');
assert.ok(res.headers['access-control-allow-methods'].includes('POST'));
assert.ok(res.headers['access-control-allow-headers'].includes('Content-Type'));
});
});
describe('Invalid JSON', () => {
let proc;
before(async () => {
proc = startServer(tmpDir);
await waitForReady(proc);
});
after(async () => { await killServer(proc); });
it('should return 400 for non-JSON body', async () => {
const res = await httpRequest('POST', '/ingest/bad-json', 'this is not json');
assert.strictEqual(res.status, 400);
const body = JSON.parse(res.body);
assert.strictEqual(body.error, 'Invalid JSON');
});
});
describe('404 for unknown routes', () => {
let proc;
before(async () => {
proc = startServer(tmpDir);
await waitForReady(proc);
});
after(async () => { await killServer(proc); });
it('should return 404 for GET /', async () => {
const res = await httpRequest('GET', '/');
assert.strictEqual(res.status, 404);
});
it('should return 404 for POST /unknown', async () => {
const res = await httpRequest('POST', '/unknown', { data: 1 });
assert.strictEqual(res.status, 404);
});
});
describe('Custom session ID', () => {
let proc;
let serverInfo;
const customSid = 'my-custom-session-42';
before(async () => {
proc = startServer(tmpDir, customSid);
serverInfo = await waitForReady(proc);
});
after(async () => { await killServer(proc); });
it('should use argv[2] as sessionId in output', () => {
assert.strictEqual(serverInfo.sessionId, customSid);
});
it('should include custom session ID in log filename', () => {
assert.ok(serverInfo.logFile.includes(`diagnose-${customSid}.log`));
});
});
describe('Multiple logs append', () => {
let proc;
let serverInfo;
const sid = `multi-${Date.now()}`;
before(async () => {
proc = startServer(tmpDir, sid);
serverInfo = await waitForReady(proc);
});
after(async () => { await killServer(proc); });
it('should append each POST as a separate JSONL line', async () => {
const payloads = [
{ step: 1, action: 'init' },
{ step: 2, action: 'process' },
{ step: 3, action: 'done' },
];
for (const payload of payloads) {
const res = await httpRequest('POST', `/ingest/${sid}`, payload);
assert.strictEqual(res.status, 200);
}
const lines = readFileSync(serverInfo.logFile, 'utf-8').trim().split('\n');
assert.strictEqual(lines.length, 3);
lines.forEach((line, i) => {
const entry = JSON.parse(line);
assert.strictEqual(entry.step, payloads[i].step);
assert.strictEqual(entry.action, payloads[i].action);
assert.strictEqual(entry._session, sid);
assert.ok(typeof entry._ts === 'number');
});
});
});
});
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |