project-layout-governance

name	project-layout-governance
description	This skill should be used when the user asks where new files should live, says code or experiment outputs are scattered, adds experiment entrypoints, writes analysis/report artifacts, or needs Git branch/worktree separation for ML experiments.
version	0.1.0

Project Layout Governance

Mission

Keep research codebases clean while making experiments easy to separate, reproduce, compare, and retire. Use this skill before writing new files, starting experiment runs, generating analysis artifacts, or deciding how Git should isolate a line of work.

When To Use

Use this skill automatically when a task will:

• create a new source, config, script, test, notebook, report, result, figure, checkpoint, log, or dataset-derived file
• start or modify an experiment, baseline, ablation, evaluation, analysis, or write-up workflow
• introduce a new directory, top-level file, run output location, or naming convention
• need branch, worktree, or commit strategy for feature work, exploratory experiments, or report-only analysis

Tiny edits inside an existing file only need a lightweight placement check: confirm the file already belongs to the right module and do not load the reference unless a new path is introduced.

When Not To Use

Skip this skill for pure read-only questions, explanations that do not create files, and edits wholly inside an already appropriate file. Do not use it to justify moving an existing project into a new layout unless the user explicitly asks for a migration plan.

Core Principles

1. Existing layout first. Inspect the project structure and reuse established package, config, test, docs, and artifact conventions before applying fallback rules.
2. No root clutter. Do not place new scripts, outputs, notebooks, figures, logs, scratch files, or reports at repository root unless the repo already defines that exact convention.
3. Separate source from runs. Reusable code lives in source modules; experiment entrypoints live in script/experiment areas; run outputs live in run/artifact areas.
4. Every experiment has identity. New experiment work needs an experiment id or stable slug, run id, config snapshot, command, seed/environment evidence, metrics path, and artifact path.
5. Tracked vs generated is explicit. Source, configs, tests, docs, and lightweight manifests are usually Git-tracked; raw data, checkpoints, logs, caches, and bulky generated artifacts are ignored or managed by the project artifact tool.
6. Git isolates work, not evidence. Use branches/worktrees to isolate code and experiment setup; keep experiment facts in experiment packages and artifact manifests.

Placement Decision

Before creating a new path, decide and record, at least mentally for tiny tasks:

kind: source | config | test | script | experiment-entry | run-output | analysis | report | doc | data | model | scratch
owner: package/module/experiment/report line
target path: ...
why this path fits the existing layout: ...
git policy: track | ignore | artifact tool | ask user
cleanup or promotion rule: keep | promote after validation | delete after use

For multi-file or experiment tasks, write the placement decision in the plan, task, change record, or experiment package.

Default Workflow

1. Inspect the current repository layout with rg --files or targeted directory reads.
2. Identify whether the task is code, config, experiment, analysis, report, docs, or scratch work.
3. If the repo has a clear convention, follow it.
4. If the repo has no convention, apply references/layout-contract.md.
5. For experiment work, allocate experiment/run identity before launching or writing outputs.
6. For Git isolation, choose branch/worktree/commit strategy before large or divergent edits.
7. Set Git/artifact policy before writing generated, bulky, private, or temporary files.
8. After writing files, verify that no unplanned root-level outputs, temporary files, or duplicate experiment directories were created.
9. Record actual paths in the change record or experiment package.

Hard Rules

• Do not create a new top-level directory just because it feels convenient.
• Do not mix reusable source code with one-off run outputs.
• Do not write generated experiment artifacts into src/, package directories, tests/, or root.
• Do not create ambiguous shared output names such as output/, results/, latest/, final.md, or metrics.json without an experiment/run parent.
• Do not move existing project files into a new convention without explicit user approval.
• If a placement decision would affect prompt/workflow rules, public APIs, data layout, or long-running experiments, capture it in a plan before editing.

Experiment Minimum

For each new experiment or ablation line, lock:

• experiment id or slug
• hypothesis or purpose
• entrypoint command
• config path and frozen override set
• run output directory
• metrics file
• artifact/report directory
• Git branch/worktree decision

When hello-scholar project assets are initialized, the experiment package remains the primary facts store. Generated analysis bundles and reports may live under the package or a project-defined artifact directory, but the package must record the paths.

Git Isolation Decision

Use git-workflow together with this skill:

• feat/<slug> for reusable product or research-code capabilities
• fix/<slug> for bug fixes
• exp/<slug> for exploratory ML experiments or ablations with code/config changes
• analysis/<slug> for post-run analysis and report-only work
• paper/<slug> for manuscript-facing writing or figure polishing

Use git worktree when two experiment branches need to run or be inspected concurrently, when long-running outputs must not be interrupted by branch switches, or when dependency/env changes are mutually incompatible.

Boundary

• This skill defines placement decisions; it does not replace git-workflow, results-analysis, results-report, or experiment package rules.
• It may recommend .gitignore, DVC, tracker, or artifact manifest policy, but it must not silently add large files or private data to Git.
• It must not migrate historical files, rename established project directories, or create new top-level conventions without explicit user approval.
• It should keep detailed matrices and examples in references/, leaving SKILL.md as a compact routing and workflow contract.

References

Load only when needed:

• references/layout-contract.md - fallback directory contract, naming rules, experiment workspace pattern, Git strategy, and tool adapters.