docs: 📝 update guides based on retrospectives

how-we-work/code-review-meetings.qmd

@@ -2,16 +2,13 @@
 title: "Code review meetings"
 ---
 
-This *optional* meeting is to go over and discuss code if any team
+This meeting type is to go over and discuss code if any team
 member has anything to discuss, share, or need help with making a
-decision.
-
-If necessary or interested, a team member will go over some code that is
-preferably, but not required, in an existing and open Pull Request. It
-can be in a draft format and doesn't need to be completed.
+decision. Specifically when it comes to something added in a pull request.
+The pull request can be in a draft format and doesn't need to be completed.
 
 During this meeting, we'll try limit the time to \~30 minutes and *at
-most* review two Pull Requests, with 15 minutes for each PR.
+most* review two pull requests.
 
 More details about this type of meeting will be added as we practice and
 do them.

how-we-work/iteration-tasks.qmd

@@ -2,9 +2,55 @@
 title: "Tasks during iterations"
 ---
 
-While specific details about what we do during an iteration is described
-in the [iteration](iteration.qmd) guide, there are some speific
-situations that need a bit more detail.
+While we have a guide specific to doing [iterations](iteration.qmd), the
+work during the iteration and the workflows or processes we follow are
+more extensive and warrant a separate guide.
+
+## Assigning issues
+
+All todo items related to an iteration are put as issues on the board
+during the planning stage and many will be unassigned. Throughout the
+iteration, individual team members self-assign the unassigned
+issues that they would like to work on. Here are some
+guidelines for self-assignment:
+
+-   Only one person (in general) should be assigned per issue, so that
+    the project board can be kept organized and so that each issue has
+    someone who is responsible for it. However, anyone can help with
+    the issue.
+    -   If a given issue might need input or help from another team
+        member, coordinate with them if need be by `@` mentioning them
+        in the issue instead of assigning them.
+-   When assigning yourself issues, keep in mind your own availability
+    and time constraints, including days/hours required for other
+    projects or events and any upcoming days off.
+-   Issues are given priority labels and, in general, try to self-assign
+    higher priority tasks first.
+
+Aside from assigning yourself to issues, if you see that something needs
+to be done, create issues as needed.
+
+-   If the issue is relevant to the current iteration, then add it to
+    the *current iteration* project board and others can self-assign as
+    desired.
+-   If the issue isn't relevant to the current iteration, don't add it
+    to the *current iteration* project board but instead to the *issue
+    list* board, and we will save it for future iterations to work on.
+
+## Task priority order
+
+While issues themselves are given a priority, our individual and team
+priorities for tasks are to, in order:
+
+-   Respond to reviewer comments on our own pull requests.
+-   Respond to issues where we are tagged/mentioned (`@`).
+-   Review pull requests from others.
+-   Work on the assigned highest priority issues.
+-   Respond to comments and questions in issues, unless it is a
+    discussion issue, where the assigned team member will seek out and
+    request our comments.
+
+## Tasks unrelated to the iteration's aim
 
 In general, tasks we work on during the iteration should support the
 overall iteration goal. However, there are several cases when we should
@@ -20,13 +66,23 @@ Specifically:
     Review" at the beginning of a new iteration and it makes sense to
     finish it during the next iteration.
 
-Likewise, while issues are assigned a priority, our individual and team
-priorities are to, in order:
+## Meetings
 
--   Respond to reviewer comments on our own pull requests.
--   Respond to issues where we are tagged/mentioned (`@`).
--   Review pull requests from others.
--   Work on the assigned highest priority issues.
--   Respond to comments and questions in issues, unless it is a
-    discussion issue, where the assigned team member will seek out and
-    request our comments.
+In general, we limit meetings as much as possible, however some can
+be very helpful. Here are some guidelines for meetings during the
+iteration:
+
+-   Have our [update meetings](update-meetings.qmd) to discuss progress,
+    next steps, and any struggles or barriers (with the work or the
+    iteration/process), as well as to present a demo of the progress
+    made within the iteration.
+-   Schedule multi-person impromptu meetings as necessary and as
+    relevant for a given task or issue, for instance a [code review
+    meeting](code-review-meetings.qmd) or a [discussion
+    meeting](discussions.qmd).
+-   Plan meetings on knowledge sharing or for code reviewing when, for
+    instance, a new and more technically complicated feature is added or
+    a new tool is used in a pull request. For the author of the pull
+    request, they will need to do a bit of preparation beforehand for
+    the meeting so that it runs smoothly and is an effective use of
+    time.

how-we-work/iteration.qmd

@@ -60,10 +60,11 @@ board](https://github.com/orgs/seedcase-project/projects/18/).
 :::
 
 An iteration starts with a first planning meeting that is scheduled well
-in advance, for between 1-2 hours and (preferably) right after the
-previous iteration's debrief and retrospective. Preferably this meeting
-is in person. The aim of the meeting to discuss and plan the specifics
-of the iteration.
+in advance, for between 30-45 minutes and either right after the
+previous iteration's debrief and retrospective or in the morning of the
+next day (to give a bit of break between meetings). Preferably this
+meeting is in person. The aim of the meeting is to discuss and plan the
+specifics of the iteration.
 
 ::: callout-note
 A basic agenda for the meeting might be:
@@ -72,7 +73,6 @@ A basic agenda for the meeting might be:
 -   Review and agree on the iteration aim and end date.
 -   Review the list of tasks already listed.
 -   Brainstorm and add any other issues as needed.
--   Assign a team member to each task.
 -   Schedule the next iteration's end and start meetings.
 :::
 
@@ -95,53 +95,26 @@ any potential issues as needed to complete the iteration aim.
 
 During the meeting, someone will share their screen (if virtual) and the
 team goes through the tasks on the board together. We'll discuss and
-decide or agree on the iteration goal (the "increment" or "milestone").
-If relevant, we can also brainstorm any other tasks that are needed
-needed to complete the increment or milestone.
-
-As we discuss each task, we collectively assign team members to the
-issues. Assign only one person per issue so that the project board can
-be kept organized and so that each issue has someone who is responsible
-for them. Anyone can help with the issue though. When assigning and
-distributing tasks, keep in mind the team member's availability and time
-constraints, including days/hours required for other projects and any
-upcoming days off.
-
-We'll review and agree on the number of tasks (aim for 5-10 per person),
-the priority label on each task (low, medium, or high), the aim of the
-iteration,\
-and the end date. We agree on and schedule the end date debrief and
-retrospective meeting, which should be approximately 2-3 hour and
-preferably before lunch, as well as the next iterations planning meeting
-(preferably on the same date, but after lunch to ensure a proper break
-before moving to a new iteration).
+decide or agree on the iteration goal (the "increment" or "milestone")
+and the end date.
+
+We'll review the current list of tasks on the board and brainstorm any
+other tasks that are needed. We'll then agree on the number of tasks in
+the iteration as well as the distribution of priority labels of the
+tasks.
+
+Then, we agree on and schedule the end date debrief and retrospective
+meeting, which should be approximately 2-3 hours and preferably before
+lunch, as well as the next iterations planning meeting. The next
+planning meeting should either be on the same date after lunch, to
+ensure a proper break before moving to a new iteration, or the next day
+to give some break between meetings.
 :::
 
 ## During the iteration
 
-We have a [guide](iteration-tasks.qmd) that describes in a bit more
-detail in how we work on tasks during an iteration. In general though,
-throughout the iteration, we will:
-
--   Have our [update meetings](update-meetings.qmd) to discuss progress,
-    next steps, and any struggles or barriers (with the work or the
-    iteration/process), as well as to present a demo of the progress
-    made within the iteration.
--   Schedule multi-person impromptu meetings as necessary and as
-    relevant for a given task or issue.
--   Work on our assigned tasks (generally focus on higher priority tasks
-    first) and coordinate with others if need be (`@` mention the people
-    involved in an issue, don't assign).
--   Add more issues if required. If the issue is relevant to the current
-    iteration, then add it to the project board so that we can determine
-    who will self-assign it during one of our meetings. If the issue
-    isn't relevant, don't add it to the project board but to the
-    relevant repository instead, and we will save it for future
-    iterations to work on.
--   Plan for "knowledge sharing" / "code review" sessions as necessary,
-    for instance to go over a new feature or tool used in a pull
-    request. For the author of the pull request, they will need to do a
-    bit of preparation before hand so that the session runs smoothly.
+We have a [guide](iteration-tasks.qmd) that describes in detail how we
+work on tasks during an iteration.
 
 ## End of iteration
 

how-we-work/update-meetings.qmd

@@ -31,7 +31,9 @@ these update meetings:
     based on the main branch or on a Pull Request.
 
 Save any detailed or technical discussion on or about code for the [code
-review meetings](code-review-meetings.qmd).
+review meetings](code-review-meetings.qmd). Likewise, for any extended
+discussions, schedule a separate [discussion meeting](discussions.qmd)
+instead.
 
 ::: callout-tip
 These meetings are held on Discord. To enter, simply go to the seedcase