Documentation and Retrospectives

This page is for maintainers adapting PRFlow’s documentation pass and local weekly retrospective to their repository.

Documentation and Deferrals

Setting	Type and accepted values	Fallback or scaffold	Tier and security note	Example
`docs.internal`	String path	`docs/internal/`	Docs skills and implementation docs pass. Keep inside the repository.	`"internal": "docs/internal/"`
`docs.external`	String path	`docs/external/`	Docs skills and implementation docs pass. Do not place confidential source material here.	`"external": "docs/external/"`
`docs.internal_enabled`	Boolean	`true`	Combined docs pass. Direct invocation of the focused skill is unaffected.	`"internal_enabled": true`
`docs.external_enabled`	Boolean	`true`	Combined docs pass. Direct invocation of the focused skill is unaffected.	`"external_enabled": true`
`docs.release_notes_file`	String path	`docs/external/release-notes.md`	Release-note skill. This is customer-facing output.	`"release_notes_file": "docs/external/release-notes.md"`
`docs.changelog_file`	String path	`CHANGELOG.md`	Release-note reconciliation.	`"changelog_file": "CHANGELOG.md"`
`docs.labels`	Comma-separated string	`Documented`	Implementation applies labels best effort after the docs pass.	`"labels": "Documented,Shipped"`
`deferred.labels`	Comma-separated string	`PRFlow,Deferred`	Follow-up issue filing. Labels are applied best effort.	`"labels": "PRFlow,Deferred"`

Weekly Retrospective

These settings describe the locally run retrospective workflow, not the shipped GitHub Actions workflows. The table identifies settings that are currently declarative rather than enforced.

Setting	Type and accepted values	Fallback or scaffold	Security or cost note	Example
`prflow_retrospective.enabled`	Boolean	Scaffold: `true`	Declarative in the current release. Setting it to false does not prevent direct invocation of `retrospective-weekly`.	`"enabled": true`
`retrospective_model`	String model identifier	Scaffold: `claude-sonnet-5`	Controls analysis cost and capability.	`"retrospective_model": "claude-sonnet-5"`
`audit_model`	String model identifier	Scaffold: `claude-opus-5`	Controls audit cost and capability.	`"audit_model": "claude-opus-5"`
`implementation_branch_prefix`	String	`claude/`	Helps select pull requests. Labels and linked issues can also select them.	`"implementation_branch_prefix": "claude/"`
`min_occurrences`	Positive integer	`2`	Higher values require more repetition before filing.	`"min_occurrences": 2`
`cooldown_days`	Nonnegative integer	`3`	Limits repeat filing for a recent open issue.	`"cooldown_days": 3`
`max_issues_per_run`	Nonnegative integer	`3`	Caps new retrospective issues per run.	`"max_issues_per_run": 3`
`max_open_issues`	Nonnegative integer	`10`	Limits the total number of open retrospective issues unless a previously fixed pattern has recurred.	`"max_open_issues": 10`
`max_open_per_category`	Nonnegative integer	`2`	Limits the number of open retrospective issues in one category.	`"max_open_per_category": 2`
`max_prs_per_run`	Positive integer	`500`	Soft cap on scanned pull requests.	`"max_prs_per_run": 500`
`audit_bundle_cap`	Positive integer	`10`	Limits how many pull request records are considered for each recurring pattern. Zero and negative values are rejected.	`"audit_bundle_cap": 10`
`diff_byte_cap`	Positive integer bytes	`204800`	Large diffs are omitted from the pull request information used for retrospective analysis.	`"diff_byte_cap": 204800`
`watched_authors`	Array of login strings	Falls back to `prflow.allowed_bots`	Restricts the primary author population.	`"watched_authors": ["my-bot"]`

Valid Example

{
  "docs": {
    "internal": "docs/internal/",
    "external": "docs/external/",
    "internal_enabled": true,
    "external_enabled": true,
    "release_notes_file": "docs/external/release-notes.md",
    "changelog_file": "CHANGELOG.md",
    "labels": "Documented"
  },
  "deferred": {
    "labels": "PRFlow,Deferred"
  },
  "prflow_retrospective": {
    "enabled": true,
    "retrospective_model": "claude-sonnet-5",
    "audit_model": "claude-opus-5",
    "implementation_branch_prefix": "claude/",
    "min_occurrences": 2,
    "cooldown_days": 3,
    "max_issues_per_run": 3,
    "max_open_issues": 10,
    "max_open_per_category": 2,
    "max_prs_per_run": 500,
    "diff_byte_cap": 204800,
    "audit_bundle_cap": 10
  }
}

⌘I