Generated Artifact Churn Rules for Registry Repositories

## Purpose

Use these rules when reviewing a registry repository where raw source entries
produce many derived files. Examples include public data feeds, category
indexes, search manifests, README sections, Raycast or plugin exports, package
bundles, generated previews, and static-site data.

Generated artifacts are useful, but they are a poor place to review contributor
intent. The source entry should explain what changed. Generated output should be
reproducible from that source and rebuilt by the trusted path the project
expects.

## Artifact Classification

Classify a changed file before reviewing content.

1. **Source file.** The human-authored entry, config, rules, guide, command, or
   source document that reviewers should inspect for intent.
2. **Generator code.** The script, package, workflow, or template that turns
   source files into derived artifacts.
3. **Generated artifact.** A file rebuilt from source or generator code, such as
   indexes, feeds, bundles, generated docs, snapshots, registry JSON, or README
   sections.
4. **Build cache or transient output.** Local output that should not be
   committed unless the repository explicitly tracks it.

When the category is unclear, ask the contributor or maintainer to identify the
source of truth before approving the diff.

## Source-Only Rules

- Contributor content PRs should add or update exactly the raw source files the
  issue asks for.
- Generated artifacts should stay out of contributor PRs unless the repository
  explicitly requires them.
- A generated file change without a source input change is a merge blocker until
  the generator or source explanation is found.
- A source file change that causes massive generated churn should be reviewed as
  a source change first, then rebuilt in maintainer automation.
- Do not accept "I ran the build" as enough evidence when the repository policy
  says generated output is maintainer-owned.

## Generated File Marking

Generated files should be easy for reviewers and platforms to recognize.

- Use `.gitattributes` or repository conventions to mark generated paths when
  appropriate.
- Keep generated paths predictable, such as `public/data/**`, `dist/**`,
  `generated/**`, `snapshots/**`, or repository-specific output directories.
- Add a short generated-file header only when the file format and project policy
  support it.
- Keep source and generated files in separate paths so reviewers can filter
  noisy output.
- Update file classification when a generated path becomes hand-authored source
  or vice versa.

## Reproducibility Rules

Generated artifacts are reviewable only when their provenance is clear.

- Name the command, workflow, or build job that regenerates the artifact.
- Record the source input path or generator code path that explains the output.
- Avoid machine-local timestamps, absolute paths, random ordering, host-specific
  metadata, and environment-dependent output when possible.
- Pin or document generator versions when output format matters.
- If generation is intentionally non-deterministic, keep it out of routine
  contributor PRs and let maintainers publish it through a controlled path.

## Reviewer Rules

- Review raw source first, generated output second.
- Compare generated artifact changes against the source input that produced
  them.
- Ask for a source-only resubmission when generated churn hides a small content
  change.
- Treat generator or workflow changes as code changes, not content-only
  submissions.
- Confirm that generated artifacts do not include private metadata, local paths,
  credentials, timestamps, or stale source URLs.
- Do not merge broad generated rewrites to fix unrelated lint, formatting,
  ordering, or timestamp changes in a content PR.

## Do Not Merge When

- the PR includes README output, registry feeds, search data, package bundles,
  previews, or generated JSON when the issue asks for one source file;
- generated artifacts changed but the source entry, generator code, or command
  is missing;
- generated output includes local paths, private identifiers, secret-like
  values, prompt excerpts, internal reviewer notes, or stale source metadata;
- the generated diff is mostly timestamp, ordering, formatting, or checksum
  churn that reviewers cannot reproduce;
- the contributor changed generator code and content in one PR without explicit
  maintainer approval;
- a closed one-shot submission is retried by force-pushing generated fixes
  instead of opening a clean source-only PR.

## Review Checklist

- [ ] {"task": "Source changed", "description": "The PR changes the raw source entry or source input requested by the issue"}
- [ ] {"task": "Generated output excluded", "description": "Generated feeds, indexes, README output, previews, bundles, and snapshots are absent unless project policy requires them"}
- [ ] {"task": "Generator known", "description": "Any generated artifact has a named command, workflow, or generator path"}
- [ ] {"task": "Diff is reproducible", "description": "Generated output avoids unexplained timestamps, random ordering, local paths, and environment-specific metadata"}
- [ ] {"task": "Files are classified", "description": "Generated paths are marked or conventionally separated so reviewers can filter churn"}
- [ ] {"task": "Privacy checked", "description": "Generated files do not expose secrets, private paths, prompts, logs, account IDs, or reviewer notes"}

## Troubleshooting

- **The project requires generated files:** include the generation command,
  source input, generator version, and a note that repository policy requires
  the artifacts.
- **The generated diff is huge:** split source changes from generator changes,
  then let maintainers rebuild artifacts in a separate automation run.
- **The source entry looks correct but generated data is stale:** merge the
  source-only PR only if project policy says generated data is rebuilt after
  merge.
- **The artifact order changes every run:** stabilize sorting or keep the output
  out of contributor PRs until the generator is deterministic.
- **A generated file contains private data:** stop normal review, remove the
  value at the source, rebuild, and check secondary artifacts before publishing.

## Duplicate Check

Checked existing rules, guides, collections, hooks, skills, commands, registry
quality code, submission gate code, open PRs, and closed PR history for
generated artifact churn, source-only PRs, generated file review, registry
artifact policy, large generated diffs, README refresh output, and source-backed
content submissions.

Adjacent content includes a source-backed content PR guide, documentation
freshness rules, generated-diff hooks, and submission gate code that enforces
single-source-file shape. This rules entry is distinct because it gives portable
do/don't behavior for reviewers and contributors deciding when generated
artifact churn should block or be moved to maintainer automation.

## References

- Git gitattributes documentation: https://git-scm.com/docs/gitattributes
- GitHub Linguist overrides: https://github.com/github-linguist/linguist/blob/main/docs/overrides.md
- GitHub changed-file display customization: https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github
- Reproducible Builds definition: https://reproducible-builds.org/docs/definition/