Standardise issue planning documentation

[ashleyshaw]

Summary

New issues are created ad-hoc without standardised planning documentation. There's no clear location or format for recording issue planning before creation.

Problem

• No centralised planning documentation
• Issues created without planning context captured
• Planning decisions lost or scattered across Slack/email
• No way to reference planning when creating related issues

Solution

Create standardised planning documentation structure:

1. Add .github/projects/active/{project}/PLANNING.md template
2. Create issue planning checklist in CONTRIBUTING.md
3. Add guidance on:
   • When to create PLANNING.md (before opening related issues)
   • What to include (goals, timeline, dependencies, constraints)
   • How to reference planning in issues (link to PLANNING.md)
4. Optional: Generate project overview from PLANNING.md in project README

Implementation Details

• Effort: 1–2 hours
• Complexity: Low
• Risk: Low (documentation-only change)
• Related: Issue templates, CONTRIBUTING.md, project metadata
• Dependencies: None

Acceptance Criteria

• PLANNING.md template created and documented
• CONTRIBUTING.md updated with planning requirements
• Existing active projects have PLANNING.md files (if applicable)
• New projects follow planning template
• CI includes check: if issue references project, verify PLANNING.md exists
• Documentation clear and discoverable

Reference

See workflow standards audit: .github/reports/audits/workflow-standards-audit-2026-05-31.md

[linear-code]

LS-809