phd-research-companion

Full-lifecycle research management for CS PhD students — literature search over real APIs, LaTeX skeletons that compile, proof ledgers, priority checks, exact-arithmetic certificates, revision tracking and pre-submission audit. Use when a research project needs to be set up, tracked, checked for nov

PhD Research Companion v2.4.0

Research lifecycle management with scientific traceability. Every command is executable and every result is derived from real data — nothing in this skill produces placeholder or fabricated output.

Core rule

This skill never invents a result. If a source cannot be reached, a PDF cannot be parsed, or a claim is unproved, the tool reports the gap. A gap that is reported is useful; a gap that is silently filled is a liability.

Two tracks

Choose once, at project creation:

	--track=theory	--track=empirical
Primary artifact	proof ledger + certificates	experiment designs + results
Novelty gate	priority before claiming	baseline comparison
Evidence	exact rational arithmetic	repeated seeded runs

Theory track adds ledger, priority, certify, audit, session.

Entry point

./run is gone (bash-only, unusable on Windows). Use:

bash

python run.py <command> [args...]
python run.py help

Relative output paths resolve against your current directory, not the skill install directory — run commands from inside the project, or pass an absolute -o / -p.

Two conventions hold across every command: the project directory is -p (-d is accepted as an alias), and the output directory is -o (--out is accepted as an alias).

Command	Script	What it does
init	init_research_project.py	create project skeleton
search	scripts/multi_source_search.py	real literature search
analyze	scripts/paper_analyzer.py	extract structure from PDFs
template	scripts/generate_latex_template.py	compiling LaTeX skeleton
experiment	scripts/create_experiment_design.py	baseline/ablation/robustness designs
revision	scripts/revision_tracker.py	revision rounds + evidence hashes
math	scripts/verify_math_notation.py	notation lint
check	scripts/check_compliance.py	pre-submission audit
ledger	scripts/proof_ledger.py	claim DAG (theory)
priority	scripts/priority_check.py	novelty check (theory)
certify	scripts/rational_certificate.py	exact-arithmetic certificate (theory)
audit	scripts/self_audit.py	proven vs publishable (theory)
session	scripts/long_horizon_session.py	mid-proof persistence (theory)

score and selftest (§10) score this repository and exist only in the full build; run.py help prints a self-check: block listing what the current build actually ships, and calls a missing optional command exit 2 with a clear message rather than a bare "missing script".

1. Project setup

bash

python run.py init -d "mirror descent vs diagonal GD" -j JMLR --track theory -o ./proj

Creates 00-dashboard/ … 07-audit-trail/, plus 02-methodology-dev/proofs and certificates on the theory track. Dashboard index.html is written to 00-dashboard/, project.json holds metadata, README.md reflects the domain you passed (not a canned example).

2. Literature search — real APIs

bash

python run.py search -q "regression data selection" -s arxiv dblp openalex -l 30 \
    -o ./proj/01-literature-survey
python run.py search -q "..." --year-from 2020 --year-to 2026 -s arxiv

Sources: arxiv (Atom API), dblp, openalex, semanticscholar. Rate-limited with retry and backoff; 429/503 back off harder.

Measured availability (verified 2026-10-11, subject to change):

Source	Status
arxiv	works over https; returns 429 when polled too fast
openalex	works, no key required
semanticscholar	frequently 429 without an API key
dblp	the public JSON endpoint sits behind a bot challenge and usually returns an HTML page

A source that answers with the wrong content type is rejected outright — the response is never parsed as data it is not. If every source fails, the command exits 2 and writes nothing.

Guarantees:

• A failed source is reported in the output and in the summary, never hidden.
• If no source succeeds, the command exits 2 and writes nothing.
• A BibTeX entry is emitted only for a record with a title; entries are checked for brace balance before being written.

Outputs search-results-<ts>.bibtex and search-summary-<ts>.md.

3. PDF analysis

bash

python run.py analyze -i ./proj/01-literature-survey --mode deep -o ./analysis

Needs pypdf (see requirements.txt); PyPDF2 and pymupdf also work. A PDF yielding fewer than 50 words is reported UNEXTRACTABLE (probably scanned) — never summarised from the filename.

4. LaTeX skeleton

bash

python run.py template -j JMLR --track theory -t "Title" -a "A Author" -o ./proj/03-paper-drafting

Venues: IEEEtran, ACM, NeurIPS, ICLR, JMLR, article. Theory track emits theorem/proof/appendix structure; empirical track emits algorithm/experiment/ablation structure.

5. Experiment design

bash

python run.py experiment --type comparison --datasets "A,B" --baselines "X,Y" -o ./proj/04-experiments
python run.py experiment --type ablation --components "c1,c2" --base-model M -o ./proj/04-experiments
python run.py experiment --type robustness --attack-types "FGSM,PGD" --perturbation-budgets "0.1,0.3" -o ./proj/04-experiments

Design files contain results: null. A design is not a result.

6. Revision tracking

bash

python run.py revision --action add_round -r 2 \
    -i "weak baseline" "lemma 4 gap" -x "fixed both" \
    -e ./proj/05-revision-rounds/round2.diff -d ./proj/05-revision-rounds
python run.py revision --action report -d ./proj/05-revision-rounds
python run.py revision --action summary -d ./proj/05-revision-rounds

Evidence files are hashed (sha256). Missing evidence is recorded as MISSING, not skipped.

7. Math notation lint

bash

python run.py math -i ./proj/03-paper-drafting/main.tex --strict

Pass every .tex file of the project, otherwise symbols defined elsewhere are false positives. Reports commands used but neither standard LaTeX nor defined in the scanned files, and labels never referenced.

8. Theory track

Claim ledger

bash

python run.py ledger -d ./proj/02-methodology-dev --init
python run.py ledger -d ./proj/02-methodology-dev --add L1 --kind lemma \
    --statement "bound on B1" --status proven --proof proofs/lemma1.tex
python run.py ledger -d ./proj/02-methodology-dev --add T1 --kind theorem \
    --statement "main" --depends L1
python run.py ledger -d ./proj/02-methodology-dev --set T1 --to proven

--set ... proven is refused while any dependency is unproven. Statuses: open, conditional, proven, refuted. The report flags cycles and dependencies on unknown claims.

Priority check — run before claiming novelty

bash

python run.py priority -d ./proj/02-methodology-dev --claim "C(d,n) = A_leq d(n)"
python run.py priority -d ./proj/02-methodology-dev --resolve P1 --verdict covered \
    --evidence https://arxiv.org/abs/2502.01234 --note "same identity, Thm 3"

Verdict defaults to unchecked. Resolving requires an http(s) evidence URL. --strict exits 1 while anything is unresolved. Unresolved means the paper must not call the claim novel.

Exact certificates

bash

python run.py certify --script ./proj/07-audit-trail/check_bound.py --strict
python run.py certify --demo

Scans the script for float contamination (float literals, float(), bare /, math/numpy) and requires a CERTIFIED / REFUTED verdict line. Write certificates with fractions.Fraction.

Self-audit

bash

python run.py audit -p ./proj --strict

Cross-reads ledger, priority records, certificates and revision history. Prints blockers (submission-stopping) and warnings (must be disclosed). A clean audit is necessary, not sufficient.

Mid-proof persistence

bash

python run.py session --start "prove C(d,n) = A_leq d(n)" -d ./proj/session
python run.py session -d ./proj/session --attempt "LP duality" --outcome failure \
    --why "dual unbounded; envelope not polyhedral"
python run.py session -d ./proj/session --resume

A failed attempt must record --why, so the dead end is not re-walked next session. --resume prints goal, last state, next action and all dead ends.

9. Pre-submission audit

bash

python run.py check -p ./proj

Every check is either implemented or reported UNVERIFIED. Unverified is not a pass. Thresholds: >= 50 BibTeX entries, >= 5 revision rounds.

check reads the track from project.json (written by init):

• theory — baseline / ablation / robustness designs are reported N/A, not failed. A theory paper has no such suite; demanding one is a category error. Instead check grades theory artifacts: a claim ledger with at least one claim, and at least one certificate in 07-audit-trail/.
• empirical — experiment designs are graded; theory artifacts are N/A.

N/A rows are excluded from both the pass count and --strict's exit code.

10. Scoring this skill

Maintainer-only. These two commands score this repository's publishing hygiene and are omitted from trimmed builds (see scripts/export_coze.py). If run.py help does not list them under self-check:, they are not present.

bash

python run.py score

Scores 9 dimensions by executing probes (compile, --help, mock detection, doc/code cross-check, test run, portability, theory-track coverage, substance, hygiene). Appends to score-history.json. Use it after any change.

Dimension	Weight	What the probe does
compilability	.12	py_compile every shipped module
runnability	.12	every script answers --help with exit 0
authenticity	.12	mock-placeholder scan + real academic API hosts
doc_consistency	.10	every file/command SKILL.md advertises exists, is wired, and every documented flag exists in that command's real CLI
test_integrity	.14	suite runs green, is non-tautological, and catches an injected mutation
portability	.08	no bash-only entrypoint, no unix-only paths
fitness	.10	theory modules present and non-trivial, --track routing
substance	.18	LOC / top-level defs / real --help text / documented commands
hygiene	.04	one version string, no dead files, no foreign attribution

substance and the mutation-catch component of test_integrity exist because a file with the right name is not a module, and a test that cannot fail is worse than no test.

A dimension score below its floor caps the total, because one catastrophic failure must not be diluted by the other dimensions' weights: test_integrity < 5 → 60, substance < 3 → 50, authenticity < 4 → 70.

A perfect score is worthless if the scorer cannot go down, so audit the scorer itself in two phases:

bash

python run.py selftest                  # both phases
python scripts/score_selftest.py --phase mutation
python scripts/score_selftest.py --phase vacuity

• Phase 1 (mutation) copies the skill to a temp directory, breaks one thing per dimension, and requires the matching score to drop. A dimension that does not react is a BLIND SPOT: it is printing a number, not measuring anything.
• Phase 2 (vacuity) removes the substance instead of adding a defect, and requires the total to stay under a ceiling. Mutation testing cannot catch this: 37 assert True tests once scored a genuine 100.00.

Current status: 9/9 dimensions falsifiable; 4/4 vacuity attacks held below their ceiling (60 / 60 / 50 / 23.2 against ceilings 70 / 70 / 60 / 40).

Both run in CI (.github/workflows/ci.yml) on every push.

Testing

bash

python -m pytest tests -q          # or: python -m unittest discover -s tests

Tests carry real assertions. A failing check fails the run — there is no "completed successfully" fallback.

Packaging

bash

python scripts/package_skill.py --check-only
python scripts/package_skill.py

Validates the frontmatter (slug-shaped name, description <= 1024 chars), compiles every module, runs --help on every command, then writes dist/phd-research-companion.zip with a MANIFEST.txt (sha256 per file) and a .sha256 beside the archive. Bytecode caches, _skillhub_meta.json (local install state, contains absolute paths) and regenerable reports are excluded. Publishing the zip is safe: it was verified by extracting it and running the full test suite and lifecycle from the extracted copy.

Integrity rules

1. Never cite an entry not verified against its source venue.
2. A claim is proven only with a proof artifact; otherwise open/refuted.
3. Numerical evidence must be reproducible by a script in 07-audit-trail/.
4. Novelty requires a resolved priority record with a URL.
5. Report gaps; do not fill them.

Known limitations (deliberate, not bugs)

• run.py score is written by this skill, so 100/100 is self-certified. The probes are executable, the weights are stated in scripts/self_score.py (change them if you disagree), and run.py selftest proves each dimension actually drops when a defect is injected and that hollow skills stay capped. What it still cannot prove is that the choice of dimensions is the right one — that judgement is yours.
• The mutation-catch probe breaks ONE module (the one most referenced by tests) inside a temp copy. It costs a second suite run, so self_score.py --fast skips it; a light suite may then score higher than it deserves.
• analyze reports keyword frequencies, not semantic understanding. It is labelled as such in its output.
• math is a linter with a standard-command whitelist. It narrows the search space; it does not certify that notation is correct.
• check reads DPI from PNG (pHYs) and JPEG (JFIF APP0) headers with stdlib only. A raster file with no density header stays UNVERIFIED.
• certify detects float contamination statically. It will not catch a value that becomes inexact at runtime through a different path.
• check's theory/empirical split depends on project.json recording the track. A project created without init has no track, and experiment checks then default to graded.
• priority record IDs are a hash of the claim text. Editing a claim's wording creates a new record rather than updating the old one.

Requirements

Core is stdlib-only. Optional: pypdf (PDF analysis), pytest (tests). See requirements.txt.

Version: 2.4.0