Refreshing Projects tracked in GitHub Issues

It’s easy to get lost in the details of a project. Every once in a while, it’s important to zoom out and look at the overall project state.

This document describes a process for this.

1. Start with Top-Level Research Questions

   • Each project should have an Area: issue on GitHub that lists the top-level research questions. For example, see this issue
   • Read through this top-level issue.

2. Update Research Questions

   • Identify any missing research questions from previous discussions.
   • Add new sub-issues under the top-level issue for any missing research questions.

3. Assess Individual Research Question Issues

   • Review each research question issue linked in the top level issue.
   • Identify subtasks that have been implemented or completed.
   • Close corresponding subtask issues.

4. Evaluate Progress and Add New Subtasks

   • For each research question: a. Check if it has any open subtasks b. If no open subtasks remain, assess whether the research question has been fully answered c. For questions requiring more work:
     • Identify the next step
     • Create a new ‘Task:’ issue
     • Include the new ‘Task:’ issue within the research question issue

5. Report Unclear Actions

   • If the next action for any research question is not clear, add a comment on the research question issue.

Issue Types

I use five issue types to manage my own work. To the extent that others find this system useful, I also use it as much as possible in collaborations.

• Task: A single action
• Note: A non-actionable piece of information
• Question: A non-actionable question
• Area: An ongoing area of responsibility, with no clear termination condition. May go on indefinitely.
• Proj: A project. Multiple tasks. A scope of work with a termination condition. Done when some objectives have been met.

What about decisions?

A decision is a task or a project depending on how many actions need to be taken. Simple decisions are tasks. Complex decisions are projects.