Task Submission Guide

Task submission is the core workflow of the Lovelace Neovim extension. This guide covers how to submit tasks, what context is collected, and best practices for writing effective task descriptions.

Basic Task Submission

From Visual Mode (Recommended)

Select code in visual mode:
vim
```
V5j  # Select 5 lines
```
Submit task:
vim
```
:LovelaceTask
```
Enter description when prompted:
```
Refactor this function to use async/await
```

From Normal Mode

You can also submit tasks without selecting code:

vim

:LovelaceTask

This submits the current file path without selection context.

What Context is Collected

When you submit a task, the extension automatically collects:

File Context

Absolute file path: /path/to/project/src/component.tsx
File type: Detected from extension
Working directory: Project root

Selection Context (Visual Mode Only)

Start line: Beginning of selection
End line: End of selection
Line count: Number of lines selected

Buffer Content

Selected text (if visual mode): Full content of selected lines
Entire buffer (if normal mode): Complete file content

Writing Effective Task Descriptions

Be Specific

❌ Bad: "Fix this"

✅ Good: "Fix the null pointer error when user.data is undefined"

❌ Bad: "Improve code"

✅ Good: "Refactor to use TypeScript generics for type safety"

Include Technical Details

✅ Good descriptions:

Convert this function to use the React hooks API instead of class components

Add comprehensive JSDoc comments explaining parameters, return values, and usage examples

Implement error handling with try-catch and proper error messages for API failures

Optimize this loop to use Array.reduce() instead of manual accumulation

Specify Desired Outcome

Include what you want and why:

Refactor this authentication flow to use JWT tokens instead of session cookies
(Why: Better for stateless API architecture)

Add TypeScript types to this component
(What: Interface for props, proper state typing, event handler types)

Context Collection Configuration

Auto-Collect Context

By default, context collection is enabled:

lua

require("lovelace").setup({
  tasks = {
    auto_collect_context = true  -- Default
  }
})

Collects:

Current file path
Selection (if visual mode)
Buffer content

Disable Auto-Collect

For tasks that don't need file context:

lua

require("lovelace").setup({
  tasks = {
    auto_collect_context = false
  }
})

Use when:

Asking general questions
Planning architecture (no code context needed)
Working with files not yet created

Task Submission Workflow

Complete Workflow Example

Open file:
bash
```
nvim src/components/UserProfile.tsx
```
Navigate to function:
vim
```
/function renderProfile
```
Select function body:
vim
```
V
}  # Select until closing brace
```
Submit task:
vim
```
:LovelaceTask
```
Enter detailed description:
```
Convert this function to a React functional component using hooks.
Replace componentDidMount with useEffect.
Replace this.state with useState.
Maintain the same prop types.
```
Receive confirmation:
```
Task submitted (task_abc123) - Status: queued
```

After Submission

The extension will:

Show task ID notification
Display initial status (queued/running)
Send progress notifications during execution
Auto-open result buffer when complete

Common Task Patterns

Code Refactoring

vim

" Select old code pattern
V10j

:LovelaceTask

Description:

Refactor this callback-based code to use async/await with proper error handling

Type Addition

vim

" Select JavaScript function
V}

:LovelaceTask

Description:

Add TypeScript type annotations: parameter types, return type, and interface for the data object

Bug Fixes

vim

" Select problematic code section
V5j

:LovelaceTask

Description:

Fix the race condition where setState is called after component unmounts.
Add cleanup in useEffect and AbortController for fetch.

Documentation

vim

" Select undocumented function
V}

:LovelaceTask

Description:

Add comprehensive JSDoc comments:
- Parameter descriptions with types
- Return value documentation
- Usage examples
- Edge cases and error scenarios

Submission States

After submitting, tasks go through these states:

Queued

Task submitted (task_abc123) - Status: queued

Meaning: Waiting for an available agent worker

Duration: Typically 0-5 seconds

What to do: Wait for agent pickup, or check agent workers:

vim

:LovelaceAgents

Running

[Task abc123] Started: Analyzing code...

Meaning: Agent worker is executing the task

Duration: 10 seconds to 5 minutes depending on complexity

What to do: Continue editing, wait for completion

Completed

[Task abc123] Completed: 2 files changed

Meaning: Task finished successfully

What happens: Result buffer opens automatically

Action: Review results in result buffer

Troubleshooting Submission Issues

"Task submission failed"

Symptom: Error notification immediately after :LovelaceTask

Solutions:

Check authentication:
vim
```
:LovelaceAuth
```
Check daemon connection:
vim
```
:LovelaceHealth
```
View error details:
vim
```
:messages
```

"Task stuck in queued"

Symptom: Task shows "queued" for more than 30 seconds

Solutions:

Check agent workers:
vim
```
:LovelaceAgents
```
If no idle workers, wait for current tasks to complete
Check task queue:
vim
```
:LovelaceTasks
```

"Context collection failed"

Symptom: Error about buffer content or selection

Solutions:

Verify file is saved:
vim
```
:w
```
Check file permissions:
bash
```
ls -la current-file.js
```
Try without selection (normal mode):
vim
```
:LovelaceTask
```

Advanced Patterns

Programmatic Submission (Lua API)

For plugin integration or automation:

lua

local lovelace = require("lovelace")
local connection = lovelace.get_connection()

connection:call("task.submit", {
  description = "Add error handling",
  context = {
    file_path = vim.fn.expand("%:p"),
    selection = {
      start = vim.fn.line("'<"),
      ["end"] = vim.fn.line("'>")
    },
    buffer_content = table.concat(
      vim.api.nvim_buf_get_lines(0, 0, -1, false),
      "\n"
    )
  }
}, function(result, error)
  if result then
    vim.notify("Task submitted: " .. result.task_id)
  end
end)

Batch Task Submission

Submit multiple tasks for parallel processing:

vim

" File 1
:e component1.tsx
VG
:LovelaceTask
" Description: Add TypeScript types

" File 2
:e component2.tsx
VG
:LovelaceTask
" Description: Add TypeScript types

" Monitor all tasks
:LovelaceTasks

Next Steps

Task Monitoring - Track task progress and status
Agent Management - View and understand agent workers
Command Reference - Full :LovelaceTask documentation
Workflow Examples - Real-world task patterns

Lovelace Developer Portal

Task Submission Guide

Basic Task Submission

From Visual Mode (Recommended)

From Normal Mode

What Context is Collected

File Context

Selection Context (Visual Mode Only)

Buffer Content

Writing Effective Task Descriptions

Be Specific

Include Technical Details

Specify Desired Outcome

Context Collection Configuration

Auto-Collect Context

Disable Auto-Collect

Task Submission Workflow

Complete Workflow Example

After Submission

Common Task Patterns

Code Refactoring

Type Addition

Bug Fixes

Documentation

Submission States

Queued

Running

Completed

Troubleshooting Submission Issues

"Task submission failed"

"Task stuck in queued"

"Context collection failed"

Advanced Patterns

Programmatic Submission (Lua API)

Batch Task Submission

Next Steps

Related Documentation

Lovelace Developer Portal