Skip to content

Docs: consolidate workflow/policy content duplicated across 4-6 files #1949

Description

@codeforester

Goal

Consolidate the issue-branch-worktree workflow, "Pre-Edit Workflow Gate," and
superseded-PR closure procedure to a single canonical document, with other
files linking to it instead of restating it.

Background

A documentation review of the process/CI/agent docs found the same workflow
content independently restated across many files, which is a real drift risk
(one copy has already partially drifted — see the companion GitHub Project
Initiative-duplicate issue for a concrete example of restated content going
stale):

  • The "Pre-Edit Workflow Gate" paragraph is restated almost verbatim in three
    files: AGENTS.md:25-39, docs/github-workflow.md:7-20, and
    .ai-context/WORKFLOWS.md:3-16.
  • The superseded-PR closure procedure is fully restated four separate times:
    AGENTS.md:85-98, skills.md:40-56, docs/github-workflow.md:461-508,
    and .ai-context/WORKFLOWS.md:134-139.
  • The full issue/branch/worktree workflow (labels, branch shape, Project
    status transitions) is independently restated across six files:
    CONTRIBUTING.md:14-71, AGENTS.md:23-101, skills.md:6-38,
    STANDARDS.md:661-691, all of docs/github-workflow.md, and
    .ai-context/WORKFLOWS.md:18-104. Only docs/github-workflow.md needs the
    full detail; the rest should point to it.
  • skills.md:16 narrows the auto-assign rule to "Codex-created issues" while
    every other file (AGENTS.md:47-49, STANDARDS.md:668-669,
    docs/github-workflow.md:79-80, .ai-context/WORKFLOWS.md:31) uses
    tool-neutral "agent-created"/"automation" language — an example of the
    restated copies already diverging in wording.

Scope

  • AGENTS.md
  • CONTRIBUTING.md
  • skills.md
  • STANDARDS.md
  • docs/github-workflow.md
  • .ai-context/WORKFLOWS.md

Acceptance Criteria

  • docs/github-workflow.md is the single canonical source for the full
    issue/branch/worktree workflow, Pre-Edit Workflow Gate, and
    superseded-PR closure procedure.
  • AGENTS.md, CONTRIBUTING.md, skills.md, STANDARDS.md, and
    .ai-context/WORKFLOWS.md each keep only the minimum summary needed
    for their own audience and link to docs/github-workflow.md for full
    detail, instead of restating it.
  • skills.md's "Codex-created" wording is aligned with the tool-neutral
    "agent-created" language used elsewhere.

Validation

git diff --check; manual read-through confirming each file still makes
sense standalone with the trimmed summary + link.

Non-Goals

  • Changing the actual workflow policy — this is a consolidation/DRY issue,
    not a policy change.

Project Metadata

  • Priority: P3
  • Size: L
  • Area: Docs
  • Initiative: Contract Hardening
  • Agent Assignment: Human first (requires editorial judgment on what to keep
    as a local summary vs. trim entirely in each of six files)

Metadata

Metadata

Assignees

Labels

documentationDocumentation improvements

Type

No type

Projects

Status
Backlog

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions