best-practices-project-state

# Best Practices: PROJECT_STATE.md Use this skill to produce a durable root-level `PROJECT_STATE.md` that a human, nightly subagent, or reviewer can inspect without reconstructing the session. The report is an evidence-backed project snapshot, not a status essay. ## Required Inputs Collect these receipts before drafting: - Current local sanity command and receipt, for example `bash scripts/sanity.sh` and `.artifacts/sanity/<timestamp>/summary.json`. - `PROJECT_KNOWLEDGE.md` and, when available, `$project-knowledge read --refresh`. - Old `$project-state` output only as an input signal; do not let it define the final structure when it is stale or Embry-specific. - Git state: branch, remote, dirty tracked/untracked counts, and recent commits. - Stale/aspirational audit: docs with TODO/future/planned language, unreferenced files, parse failures, missing imports, and known broken tests. - Browser-oracle resolve/doctor receipt for the project. - Research receipts from `$brave-search`, `$github-search`, and `$dogpile`. - `$ask` WebGPT review artifacts for the assembled review bundle. ## Research Workflow Run research before WebGPT review so the reviewer sees evidence, not just local assumptions. 1. Use `$brave-search` for current product/library/research landscape. 2. Use `$github-search` for comparable repositories, code patterns, issues, README positioning, and maintenance signals. 3. Use `$dogpile` for multi-source synthesis and ambiguity handling. Preserve `dogpile_partial_results.json`, final Markdown/HTML reports, and provider degradation notes. 4. Build a review bundle with local receipts plus research outputs. 5. Use `$ask` through the real runtime for WebGPT or a broader panel. Attach the bundle content or a readable bundle file; a browser tab cannot inspect bare paths by itself. 6. Reconcile reviewer claims against local evidence before writing `PROJECT_STATE.md`. ## Required Report Shape `PROJECT_STATE.md` must include these top-level sections: 1. `# Project State: <project>` 2. `## Executive Summary` 3. `## Evidence Receipts` 4. `## What Works` 5. `## Outstanding Gaps` 6. `## Aspirational Or Stale Material` 7. `## Missing Or Regressed Capabilities` 8. `## Competitive And Research Landscape` 9. `## Project Positioning` 10. `## Risks And Unknowns` 11. `## Recommended Next Actions` Each material claim must cite a receipt path, command output, research artifact, or reviewer artifact. If evidence is missing, write `not established` and name the missing receipt. ## Claim Discipline - Distinguish `working`, `partially working`, `not established`, `stale`, `aspirational`, and `missing`. - Do not infer production readiness from mocked tests, empty logs, absent errors, or reviewer prose. - Mark competitor/research claims with source artifacts and date. - Keep project positioning sober: say where the project can own a niche only when local capabilities and external comparison support it. - Do not hide failed checks. Failed tests and degraded providers belong in `Evidence Receipts` and `Risks And Unknowns`. ## Project-Knowledge Composition After `PROJECT_STATE.md` is written and validated: - Update `PROJECT_KNOWLEDGE.md` with a compact section pointing to the state report and the key new durable lessons. - Run `$project-knowledge sync` when available so memory recall can find the state summary. - Do not replace `PROJECT_KNOWLEDGE.md` with `PROJECT_STATE.md`; the former is rolling shared context, the latter is a dated assessment artifact. ## Validation Run: ```bash bash scripts/sanity.sh uv run --project . python scripts/validate_project_state.py /path/to/PROJECT_STATE.md ``` The validator checks required sections and basic receipt-path evidence. It is a format/evidence-floor gate only; it does not prove the project is healthy. For live review readiness, run the opt-in gate: ```bash bash scripts/sanity-live.sh /path/to/project ``` The live gate calls the real browser-oracle resolver and checks that the research/review skill entrypoints needed by this workflow are present. It does not replace the actual `$brave-search`, `$github-search`, `$dogpile`, or `$ask` run receipts required for a final `PROJECT_STATE.md`. ## Nightly Use Nightly subagents should be incremental: - Reuse unchanged receipts when files and commands have not changed since the last valid state report. - Rerun sanity, best-practices, research, and reviewer steps for changed files, changed dependencies, changed claims, stale receipts, or failed prior gates. - Commit and push only the coherent state-report slice when validation and required local checks pass.