Generated Project Workflows

---
name: generated-project-workflows
description: "Guide agents working inside generated Cookiecutter Data Science
  projects through layout, Makefile workflows, environment-manager commands,
  scaffold modules, validation, and common failures."
disable-model-invocation: true
metadata:
  disco-role: operating
license: MIT
---

# Generated Project Workflows

Use this sub-skill when you are already working inside a project generated by Cookiecutter Data Science (CCDS) and need to understand or modify its runtime workflow. CCDS 2.3.0 generates a data-science project whose exact files and commands depend on selected options for environment manager, dependency file, testing, linting, docs, cloud storage, license, and code scaffold.

## Scope

This sub-skill covers generated-project operation after a project exists:

- Directory layout and the purpose of `data/raw`, `data/external`, `data/interim`, `data/processed`, `docs`, `models`, `notebooks`, `references`, `reports/figures`, the package module, `pyproject.toml`, `setup.cfg`, tests, `.env`, `.gitignore`, and `Makefile`.
- CCDS project opinions: raw data is immutable, analysis is a DAG, most data stays out of source control, notebooks are for exploration/communication, reusable code belongs in package modules, secrets/config go in `.env`, and Make is the task runner.
- Generated Makefile commands such as `requirements`, `clean`, `lint`, `format`, `test`, `sync_data_down`, `sync_data_up`, `create_environment`, `data`, and `help`.
- Environment-manager-specific commands for `conda`, `virtualenv`, `pipenv`, `uv`, `pixi`, `poetry`, and `none`.
- Generated code scaffold modules when `include_code_scaffold=Yes`, and the empty-package result when `include_code_scaffold=No`.
- Option-dependent docs, tests, linting, cloud sync, validation, and troubleshooting.

## Route elsewhere

- If the task is to choose CCDS answers before project generation, route to `../template-options-and-hooks/`.
- If the task is to run the `ccds` CLI or reason about Cookiecutter CLI flags, route to `../project-generation-cli/`.

## Bundled references and script

- Read [references/project-layout.md](references/project-layout.md) when you need to map generated paths to their intended purpose or audit option-dependent files.
- Read [references/makefile-reference.md](references/makefile-reference.md) before running, editing, or debugging generated `Makefile` rules.
- Read [references/environment-managers.md](references/environment-managers.md) when dependencies, environment creation, activation, or valid environment-manager/dependency-file pairings matter.
- Read [references/scaffold-reference.md](references/scaffold-reference.md) before editing the generated package scaffold or deciding how to refactor notebook code into reusable modules.
- Read [references/troubleshooting.md](references/troubleshooting.md) when validation, environment setup, linting, tests, cloud sync, or scaffold imports fail.
- Run [scripts/validate_generated_project.py](scripts/validate_generated_project.py) for a read-only structural validation of a generated project; pass explicit expectations when known, or use the default `auto` detectors for option-dependent features.

## Operating procedure

1. Confirm you are at the generated project root: it should have `Makefile`, `README.md`, `pyproject.toml`, `.env`, `.gitignore`, data subdirectories, and one importable package directory containing `__init__.py`.
2. Identify option-dependent features rather than assuming one fixed tree: docs may be `mkdocs` or `none`, tests may be `pytest`, `unittest`, or `none`, linting may be `ruff` or `flake8+black+isort`, code scaffold may be present or absent, and cloud sync rules only appear when storage was configured.
3. Use `make` or `make help` to list available rules before invoking them. `make requirements`, `make create_environment`, `make lint`, `make format`, `make test`, `make data`, and sync rules are generated conditionally.
4. Do not mutate raw data in place. Move data through a reproducible DAG from `data/raw` or `data/external` to `data/interim` and finally `data/processed`, with reports and figures under `reports/`.
5. Keep credentials and machine-specific configuration in `.env`; do not commit `.env` or bulk data unless the project has explicitly changed the default policy.
6. Prefer editing package modules for reusable logic and notebooks for exploration/communication. After dependency installation, the package is intended to be used as an editable local package.
7. Validate changes with the bundled read-only validator and then with the project's own available `make` rules only when the required manager CLIs, credentials, and network access are intentionally available.