This guide teaches you how to use Vikunja as a student who is reading and updating team tasks for the first time.

Vikunja is the team's issue tracker at https://tasks.bert133.dev. An issue tracker is a shared list of work, questions, and problems. On our team, most items in Vikunja are called tasks. A task can be a planned piece of work, like adding a new dashboard button, or a problem report, like the robot code not seeing a sensor.

If you have never used a tool like this before, the main idea is simple: write down the work clearly enough that another student or mentor can understand what happened without asking you to repeat the whole story.

What Vikunja is for

Use Vikunja when the team needs to remember something after the current conversation ends.

Good reasons to use Vikunja:

• You found a robot problem that needs to be investigated.
• You are planning a programming, mechanical, electrical, scouting, or media task.
• You are blocked and need a mentor or another student to help.
• You finished work and need the team to know what changed.
• You need to track work before a deadline, practice, event, or check-in.

Do not rely on memory or chat messages for important work. Chat is good for quick conversation. Vikunja is where the team keeps the record.

The parts of Vikunja you will use most

Projects

A project is a group of related tasks. Examples might include Robot code, Scouting app, Mechanical, or Competition packing.

Every task belongs to one project. If you create a task in the wrong project, it can be moved later. Getting the task written down is more important than getting every detail perfect on the first try.

Tasks

A task is one thing the team needs to do, check, fix, or remember.

A task usually has:

• A title — the short name people see in the task list.
• A description — the details someone needs before starting.
• An assignee — the person responsible for the next move.
• Labels — short tags like programming, mechanical, blocked, or needs mentor.
• A due date — the day the task needs to be finished, if timing matters.
• Comments — updates added after the task is created.
• Attachments — photos, screenshots, logs, notes, or other files.
• Relations — links to other tasks, such as a task that blocks this one.

A task can have more than one assignee, label, comment, attachment, or related task.

Comments

A comment is an update on a task. Comments are where the story continues after the task is created.

Use comments when:

• You tried something.
• Something changed.
• You found new information.
• You need help.
• You fixed part of the problem.
• You confirmed that the work is done.

You can mention a person with @username if they need to see the update. Do not overuse mentions. Mention someone when they need to act, not every time you write a note.

Labels

A label is a short tag that helps people find related tasks.

Useful labels might include:

• programming
• mechanical
• electrical
• drive-team
• blocked
• needs mentor
• competition
• problem report

Labels help the team filter a long list. For example, a programming student can look for programming tasks, or a mentor can look for tasks marked needs mentor.

Assignees

An assignee is responsible for keeping the task moving.

Being assigned does not mean you must solve the whole thing alone. It means the team knows who is watching the task. If you get stuck, your job is to leave a clear comment and ask for help.

Due dates and reminders

A due date marks when a task needs to be finished. Vikunja highlights overdue tasks when the due date has passed.

Use a due date when the timing matters, such as:

• Before a Wednesday check-in.
• Before drive practice.
• Before a competition.
• Before a robot inspection or demo.

A reminder can notify you before a task is due. Use reminders when you personally need a nudge.

Do not add due dates to every task. A due date should mean something.

Attachments

An attachment is a file added to a task.

Useful attachments include:

• A photo of wiring.
• A screenshot of an error.
• A short video of the robot behavior.
• A log file.
• A drawing, checklist, or notes file.

If a picture explains the problem better than words, attach it. Still write a description so people know what they are looking at.

Related tasks and blockers

A related task is another task connected to the current one. A blocker is a task that must happen before this task can continue.

Example:

• Tune arm position control is blocked by Repair arm encoder wiring.

Writing blockers down helps the team focus on the real next step.

Views: different ways to see the same tasks

Vikunja can show the same project in different views. The tasks do not change. Only the layout changes.

List view

List view shows tasks in a straightforward list. Start here if you are new.

Use List view when:

• You want to read tasks one at a time.
• You want to add a task quickly.
• You want the least confusing layout.

Kanban view

Kanban view shows tasks as cards in columns, often called buckets. A team might use buckets such as Backlog, Doing, Blocked, and Done.

Use Kanban view when:

• You want to see status at a glance.
• You are in a check-in meeting.
• You need to move tasks between stages.

In Vikunja, moving a task into the done bucket can mark the task done. Moving it back out can reopen it.

Table view

Table view looks more like a spreadsheet. It is useful when you need to compare fields, such as assignee, due date, priority, and labels.

Use Table view when:

• The project has many tasks.
• You are checking missing assignees or due dates.
• You need to sort or filter by fields.

Gantt view

Gantt view shows tasks on a timeline. It is useful for schedule planning when start dates, end dates, and dependencies matter.

Most students will not need Gantt view every day. It is more useful when planning work across several days or weeks.

Filters and saved filters

A filter shows only tasks that match certain rules.

Examples of things you might filter for:

• Tasks assigned to you.
• Tasks with the blocked label.
• Tasks due this week.
• Tasks that are not done yet.
• Tasks marked high priority.

A saved filter keeps a filter available so you can use it again. For example, My open tasks could show unfinished tasks assigned to you across several projects.

You do not need to learn filter syntax on your first day. Start by using the project views and labels. Filters become useful when the task list gets crowded.

The two main kinds of tasks

Most student-created tasks should be one of two types:

1. Development TODOs — planned work the team wants to do.
2. Problem reports — something went wrong and needs diagnosis or repair.

These two kinds of tasks need different writing styles.

A development TODO should focus on what done looks like.

A problem report should focus on what was observed.

Development TODOs

A development TODO is planned work. It describes something the team wants to build, change, test, or prepare.

Examples:

• Add a driver button for slow turn mode.
• Create a checklist for competition battery charging.
• Test whether the intake sensor changes when a note passes through.
• Update the scouting form with a climb question.
• Mount labels on the spare motor controllers.

A good development TODO is specific

A vague task is hard to start.

Weak titles:

• ❌ robot code
• ❌ fix scouting
• ❌ dashboard
• ❌ clean up

Better titles:

• ✅ Add dashboard indicator for intake sensor state
• ✅ Remove unused autonomous routines from the chooser
• ✅ Add scouting question for whether a robot can climb
• ✅ Label spare motor controllers with device IDs

The better titles name the actual work.

A good development TODO is actionable

Actionable means someone can read the task and know the next physical or mental action to take.

Good action words include:

• Add
• Remove
• Test
• Measure
• Write
• Update
• Mount
• Label
• Review
• Compare

If the task title does not contain an action, check whether it is only a topic.

Topic:

Intake sensor

Actionable task:

Test whether the intake sensor changes when a note passes through

A good development TODO has a definition of done

The definition of done is how the team knows the task can be checked off.

Ask yourself:

• What should exist when this is finished?
• What should work when this is finished?
• What should be tested before this is closed?
• Who needs to be told or shown?

Examples:

Task	Clear definition of done
Add dashboard indicator for intake sensor state	The dashboard shows true and false correctly when a note is moved through the intake.
Label spare motor controllers with device IDs	Every spare motor controller in the programming bin has a visible ID label.
Update scouting form with climb question	The form has the new climb question, and one test submission appears correctly in the results sheet.

Write the definition of done in the task description if it is not obvious from the title.

What to put in a development TODO

When you create a development TODO, include:

1. What needs to change.
2. Why the team wants it.
3. What done looks like.
4. Any important limits or notes.

Example:

Add a dashboard indicator for the intake sensor state.

This helps the drive team and programming team see whether the robot thinks it has a note.

Done means the dashboard shows the sensor as true when a note is in the intake and false when no note is present. Test it with the real robot or the practice electronics board before closing this task.

When to close a development TODO

Close the task when the definition of done is met.

Before closing it:

1. Leave a comment saying what changed.
2. Mention any test you ran.
3. Add a link or note if the work is saved somewhere else, such as Forgejo.
4. Move the task to Done or tap Done in the task.

Good closing comment:

Added the dashboard indicator and tested it on the practice electronics board. It changes to true when the sensor is blocked and false when the sensor is clear. Closing this task.

Problem reports

A problem report is a task that records something wrong, surprising, broken, or unclear.

Examples:

• The robot drives backward when the joystick is pushed forward.
• The intake motor does not move during teleop.
• The dashboard shows no camera image.
• The scouting form crashes after tapping Submit.
• The arm moves to the wrong height when scoring.

Problem reports are important because the first observation is often the best clue. If nobody writes it down, the team may waste time rediscovering the same problem later.

Start with the Condition

When you create a problem report, focus first on the Condition.

The Condition is what you observed. It should describe what happened, when it happened, and what you expected instead.

Good condition notes answer questions like:

• What were you trying to do?
• What did you tap, move, run, or test?
• What happened instead?
• What did you expect to happen?
• Did it happen once, sometimes, or every time?
• What robot, device, browser, or workspace were you using?
• Was there an error message?
• Is there a photo, screenshot, video, or log that should be attached?

You do not need to know the cause before creating the task. A clear condition is enough.

Weak problem report:

Arm broken.

Better problem report:

When testing the arm on the practice robot, the arm moved down instead of up after tapping the Raise Arm button on the dashboard. This happened three times in a row. I expected the arm to move upward to the scoring position. No error message appeared on the dashboard.

The better report gives the next person something to investigate.

The 4 Cs of diagnostics

For problem reports, use the 4 Cs:

1. Condition — what was observed.
2. Cause — why it happened.
3. Correction — what was changed to fix it.
4. Confirmation — how the team proved the fix worked.

You usually know the Condition first. The other three often come later.

1. Condition: what was observed

The Condition belongs in the original task description.

Include:

• The exact behavior you saw.
• What you were doing when it happened.
• What you expected to happen.
• Whether it repeats.
• Any useful context.
• Any screenshots, photos, videos, or logs.

Condition example:

During drive practice, the robot stopped responding to the driver's forward/backward joystick movement after about 20 seconds. Turning still worked. This happened in two practice matches on the carpet. I expected forward/backward drive to keep working until the robot was disabled.

If the problem is hard to explain, attach a short video and write what the viewer should notice.

2. Cause: why it happened

The Cause is the reason the problem happened.

Do not guess too strongly at the start. It is okay to include a hypothesis, which means a possible explanation that still needs to be checked.

Good early wording:

Possible cause: this might be related to the left drive motor controller, because the problem started after that controller was replaced. Not confirmed yet.

Avoid wording like this unless you have proof:

The new motor controller is bad.

The first version helps the team investigate. The second version can send the team in the wrong direction.

When the cause is confirmed, add it as a comment.

Cause comment example:

Confirmed cause: the left drive motor controller CAN ID was set to 4, but the code expected 3. The robot log showed repeated warnings for missing CAN ID 3.

3. Correction: what changed

The Correction is what someone did to fix the problem.

Add corrections as comments, not by replacing the original condition. The original report should stay visible so the team can understand the full story.

Correction comment example:

Correction: changed the left drive motor controller CAN ID from 4 to 3, then power-cycled the robot.

A correction should be specific. Fixed it is not enough.

4. Confirmation: how the fix was checked

The Confirmation is how the team proved the correction worked.

Confirmation comment example:

Confirmation: drove the robot for three 2-minute practice runs. Forward/backward and turning both worked for the full runs. The dashboard showed no missing CAN ID warnings.

Confirmation matters because a change is not the same as a fix. The team needs to know the problem was actually checked.

Problem report template

Use this format when you create a problem report:

Condition:
What did you observe?

Expected behavior:
What did you expect to happen instead?

How to repeat it:
What steps make it happen again? If you do not know, say when you saw it.

Context:
What robot, device, browser, workspace, field setup, or match situation matters?

Attachments:
Add photos, screenshots, videos, or logs if they help.

Possible cause:
Optional. Only include this if you have a useful hypothesis. Say "not confirmed" if you are guessing.

Correction and confirmation should usually be added later as comments.

Example problem report

Title:

Intake motor does not run from driver button

Description:

Condition: During teleop testing on the practice robot, the intake motor did not move when the driver held the right bumper. The shooter motor still worked. This happened every time we tried it during the last test session.

Expected behavior: The intake motor should run while the right bumper is held.

How to repeat it: Enable teleop, hold the driver's right bumper, and watch the intake motor.

Context: Practice robot, classroom carpet, driver controller plugged into port 0.

Attachments: Short video attached showing the driver holding the button and the intake staying still.

Possible cause: Not confirmed. Could be button mapping, motor controller wiring, or the intake command not being scheduled.

Later comment:

Cause: the driver controller mapping used left bumper in code, but the drive team was told to use right bumper.

Later comment:

Correction: changed the intake command binding to right bumper and updated the driver controls note.

Later comment:

Confirmation: tested in teleop on the practice robot. The intake runs while right bumper is held and stops when released. Tested five times.

How to update a task during work

When you work on a task, leave a comment before you walk away.

A useful update includes:

1. What you tried.
2. What happened.
3. What still needs to happen.
4. Whether you are blocked.

Weak update:

Worked on it. Still broken.

Better update:

Checked the dashboard and confirmed the sensor value stays false when a note passes through. I also checked that the sensor has power. Next step is to check whether the signal wire is connected to the expected port. Marking this blocked until a mentor can help inspect the wiring.

The better update saves the next person time.

When you are blocked

A task is blocked when you cannot make progress until something else happens.

Examples:

• You need a mentor decision.
• You need a part installed before you can test code.
• You need access to a project or file.
• Another task must be finished first.
• The robot is not available.

When you are blocked:

1. Add the blocked label if the project uses it.
2. Leave a comment explaining what is blocking you.
3. Say what help or decision you need.
4. Add a related task if another task is the blocker.
5. Tell a mentor if the block is urgent.

Blocked comment example:

Blocked because the encoder is not mounted yet, so I cannot test arm position control on the robot. I added a related task for mounting the encoder. I can keep working in simulation, but the final test needs the real robot.

Before you mark a task done

Do not mark a task done only because you spent time on it. Mark it done when the work is actually complete.

Before marking done, check:

1. Is the definition of done met?
2. Did you test or check the result?
3. Did you leave a comment saying what changed?
4. Are there any follow-up tasks that should be created?
5. Should a mentor or teammate know before it is closed?

If the task is mostly done but needs another step, leave it open and write the next step.

Your first-week Vikunja habits

Start with these habits:

1. Open https://tasks.bert133.dev at the start of a work session.
2. Check tasks assigned to you.
3. Read the description before starting work.
4. Leave a comment when you learn something useful.
5. Mark tasks blocked when you cannot move forward.
6. Mark tasks done only when the definition of done is met.
7. Ask a mentor if you are not sure where to put a task.

You do not need to be perfect. You do need to make the work visible. A clear task helps the whole team remember what happened and decide what to do next.