Maquetar Registro: Sub-task Template Guide

When Should You Use This Template?

This template is specifically designed for technical tasks that fall into two main categories. Firstly, it's perfect for sub-tasks that are an integral part of a larger User Story (US). Think of it as breaking down a big goal into smaller, manageable pieces. For instance, if your User Story is "Login and Registration" (let's call it issue #1), then the sub-tasks would be things like "Layout the form" (directly related to #1), "Connect to API" (also related to #1), and "Implement Validations" (again, related to #1). Each of these is a distinct technical step contributing to the overall user story. Secondly, this template is also suitable for independent technical tasks. These are tasks that don't necessarily tie directly into a specific user-facing feature but are crucial for the project's health and progress. Examples include "Set up CI/CD pipelines," "Document the API thoroughly," or "Research and evaluate a new library like X." These tasks are essential for maintaining and improving the development process.

However, it's crucial to understand when not to use this template. Avoid using this sub-task template for bugs or refactors. These types of issues should be addressed directly within the original bug or refactor issue. Creating separate sub-tasks for them can lead to confusion and fragmented tracking. Furthermore, do not use this template if you are dealing with a completely new functionality for the end-user. For such cases, you should opt for a "User Story" or "Feature Request" template, as these are designed to capture and manage larger, user-centric features from inception.

By adhering to these guidelines, you ensure that the right tasks are captured using the most appropriate template, leading to clearer communication, better organization, and more efficient development workflows. Remember, the goal is to make complex projects manageable by breaking them down systematically and tracking each component effectively.

Related User Story or Feature (Optional)

If this specific sub-task is a component of a larger User Story or Feature, it's essential to link it clearly. This connection provides context and helps everyone involved understand how this piece fits into the bigger picture. You can indicate this relationship by referencing the main issue number. For example, you would fill in: "Belongs to: #issue-number", replacing #issue-number with the actual ID of the parent User Story or Feature. This cross-referencing is vital for maintaining traceability throughout the development lifecycle. It allows teams to easily navigate between the main objective and its constituent parts, ensuring that all aspects of a larger requirement are addressed.

If, on the other hand, this sub-task is a standalone technical task – like setting up a new testing framework, writing documentation for an existing API, or investigating a potential performance bottleneck – then you should leave this field empty. This signifies that the task is independent and doesn't directly roll up into a specific user-facing story. This distinction is important for planning and prioritization, as independent tasks often have different timelines and dependencies than those embedded within a larger user story. Properly identifying whether a task is linked or independent helps in accurately assessing project scope and resource allocation. It prevents clutter in the User Story tracking and ensures that standalone technical improvements are not overlooked.

Maintaining this clear distinction between linked and independent tasks enhances the overall clarity of your project management system. It allows for a more granular view of progress and facilitates easier reporting on different types of work. Whether it's a small step towards a grander user experience or a vital piece of infrastructure work, documenting its relationship (or lack thereof) is a key part of effective task management.

Sub-task Description

This section is dedicated to providing a clear and concise technical description of the specific work that needs to be accomplished within this sub-task. It's crucial that the description is detailed enough for any developer picking up the task to understand exactly what is expected. When describing the technical implementation for a task like "Maquetar registro" (Layout registration), you would elaborate on the specific UI components required. This might include detailing the input fields (username, email, password, confirm password), the buttons (submit, cancel, or links to other pages like "Forgot Password"), and any associated validation messages or error states that need to be visually represented. You should specify the layout structure, how elements are aligned, and the responsiveness required for different screen sizes (mobile, tablet, desktop).

For tasks involving APIs or backend logic, the description should outline the expected endpoints, request methods (GET, POST, PUT, DELETE), required parameters, and the structure of the request and response payloads. For database-related tasks, specify the data models, necessary migrations, and any complex queries that need to be written or optimized. The goal here is to eliminate ambiguity. If the task involves implementing a specific authentication flow, detail the steps, the libraries to be used, and any security considerations. For testing tasks, clearly define the scope of testing – unit tests for specific functions, integration tests for service interactions, or end-to-end tests simulating user flows.

Even for seemingly simple tasks like configuration or research, a precise description is vital. For configuration, list the specific settings, environment variables, or dependencies that need to be managed. For research tasks (often called "spikes"), clearly state the problem to be solved, the potential solutions to investigate, and the expected outcome (e.g., a recommendation, a proof-of-concept).

In essence, the sub-task description acts as a mini-specification. It should answer the fundamental questions: What needs to be done? Why is it important (briefly, if not obvious from the parent US)? What are the key technical requirements? What are the expected deliverables? The more precise and comprehensive this description, the smoother the implementation process will be, reducing the chances of misinterpretation and rework. A well-written description empowers the developer to start working efficiently and confidently, knowing exactly what success looks like from a technical standpoint.

Task Type

Categorizing the task accurately is fundamental for effective project management and workflow organization. This helps in understanding the nature of the work, estimating effort, and assigning the right resources. We have defined several clear categories for the type of task you are undertaking. Each category is represented by an emoji for quick visual recognition and a descriptive label.

• [ ] 🎨 UI/UX: This covers tasks related to the user interface and user experience. It includes creating new visual components, applying styles, defining layouts, and ensuring a seamless user flow. If your sub-task involves making the registration form look good and function intuitively on the screen, this is the category.
• [ ] 🔌 API/Endpoint: Use this for tasks that involve creating new API endpoints or modifying existing ones. This is crucial for backend development, enabling communication between different parts of the system or with external services.
• [ ] 🗄️ Base de Datos: Select this if the task pertains to database operations, such as defining new data models, creating database migrations to alter the schema, or writing and optimizing complex queries.
• [ ] 🔐 Autenticación/Autorización: This category is for tasks specifically focused on implementing or modifying user authentication (verifying identity) and authorization (determining permissions) mechanisms.
• [ ] ✅ Testing: Choose this for any task related to writing or improving tests, including unit tests, integration tests, or end-to-end (E2E) tests. Ensuring code quality and reliability is paramount.
• [ ] 📚 Documentación: If the task involves updating or creating documentation – such as API documentation, user guides, or architectural diagrams – this is the category.
• [ ] ⚙️ Configuración: This applies to tasks related to setting up the development environment, CI/CD pipelines, deployment scripts, or any other system configuration aspects.
• [ ] 🔍 Investigación: Use this for "spikes" or proof-of-concept (POC) tasks where the goal is to explore a technical problem, evaluate potential solutions, or gather information before committing to an implementation path.

A crucial note is to remember that bugs and refactors should not be categorized here. They should be managed directly within their original issues. This template is for new work or improvements, not for fixing existing problems or restructuring code, which have their own dedicated tracking mechanisms. By correctly selecting the task type, you provide valuable metadata that aids in reporting, planning, and understanding the project's overall technical landscape. This structured approach ensures that every piece of work is accounted for and categorized appropriately.

Component

Identifying the primary component or layer of the application that this sub-task affects is essential for understanding its scope and impact. This helps in assigning the task to the correct team or individual and ensures that dependencies between different parts of the system are managed effectively. We've simplified this into three main areas:

• [ ] Frontend: Select this if the task primarily involves work on the client-side of the application. This includes everything the user interacts with directly in their browser or on their device – the user interface, user experience, client-side logic, and interactions with the backend via APIs. For our "Maquetar registro" example, this would be the most relevant choice, as it focuses on the visual presentation and user interaction of the registration form.
• [ ] Backend: Choose this if the task's main focus is on the server-side of the application. This encompasses managing databases, building APIs, handling business logic, security, and server configurations. Tasks like creating registration API endpoints or setting up database schemas would fall under this category.
• [ ] Fullstack: This option is for tasks that span across both the frontend and backend. If an implementation requires changes or coordination in both layers simultaneously – for example, developing a new feature that involves significant modifications to both the UI and the corresponding API endpoints and database structures – then "Fullstack" is the appropriate choice. It signifies a task that requires a holistic view and potentially involvement from developers with expertise in both domains.

This categorization is more than just a label; it helps in visualizing the flow of work and potential bottlenecks. For instance, if a "Fullstack" task is blocked by a backend dependency, it's immediately clear that the backend component needs prioritization. Similarly, understanding that a "Frontend" task relies on a specific API endpoint being ready helps coordinate efforts between frontend and backend teams. By clearly defining the component, you contribute to a more organized and efficient development process, ensuring that tasks are tackled by the right people and that inter-component dependencies are managed proactively. This clarity is particularly important in larger teams or projects where different specialists work on distinct parts of the application.

Affected Files/Areas

To ensure that no part of the codebase is overlooked and to provide clarity on the scope of the changes, it's crucial to list all the files, modules, or specific areas of the code that will be affected by this sub-task. This detailed list serves as a roadmap for the developer implementing the task and for the reviewer who will be assessing the changes. It helps in understanding the ripple effect of the modifications and in identifying potential conflicts or integration issues.

For the "Maquetar registro" (Layout registration) sub-task, you might list files like:

• src/components/forms/RegistrationForm.tsx (The main component for the form)
• src/styles/components/_forms.scss or src/styles/Registration.module.css (For styling the form elements)
• src/pages/Registration.tsx (If the form is part of a specific page layout)
• src/utils/validation.ts (If new validation rules are added or modified)

If the task involves backend changes, you would list relevant files like:

• src/controllers/authController.ts (For API endpoint logic)
• src/models/User.ts (For database schema definitions)
• src/routes/authRoutes.ts (For defining API routes)
• database/migrations/XXXX_create_users_table.ts (For database schema changes)

For configuration tasks, you might list configuration files or directory paths:

• .env variables or config/app.json
• Dockerfile or docker-compose.yml

This list should be as specific as possible. Instead of just saying "forms module," specify the exact component file. This level of detail is invaluable during code reviews, as reviewers can quickly locate the relevant code sections. It also aids in debugging, as developers can easily pinpoint where issues might arise. Furthermore, maintaining this list helps in understanding the overall architecture and dependencies within the project. It acts as a living documentation of code impact, ensuring that changes are well-understood and managed. By meticulously listing affected areas, you contribute significantly to code quality, maintainability, and collaborative development.

Proposed Implementation

This section is where the developer outlines their planned approach to implementing the sub-task. It's a chance to think through the technical steps, choose the right tools or libraries, and perhaps even sketch out the core logic. This doesn't need to be an exhaustive step-by-step guide but rather a high-level overview of the strategy. For the "Maquetar registro" (Layout registration) task, a proposed implementation might look like this:

"Use the existing Input and Button components from the shared UI library. Structure the form using a vertical layout. Implement responsiveness using CSS media queries to ensure it adapts to mobile and desktop views. Add basic client-side validation for required fields and email format using a library like Yup or Zod, displaying error messages below each invalid field."

If the task involved a backend component, such as "Create registration endpoint," the proposal might be:

"Create a POST /api/v1/auth/register endpoint using Express.js. This endpoint will receive user credentials (username, email, password) in the request body. It will validate the input using a predefined schema. If valid, it will hash the password using bcrypt and save the user data to the users table via the Sequelize ORM. Finally, it will return a success response with the newly created user's ID or an appropriate error message."

Including example code snippets or pseudocode here can be incredibly beneficial. It allows the developer to visualize the solution and communicate complex logic concisely. This is particularly useful for tricky algorithms, specific API interactions, or intricate UI state management. For example, a pseudocode snippet might illustrate how form data will be processed or how an API call will be structured.

// Example pseudocode for form submission:
async function handleRegistrationSubmit(formData) {
  try {
    const validationErrors = await validateRegistrationData(formData);
    if (validationErrors.length > 0) {
      displayErrors(validationErrors);
      return;
    }
    const response = await api.post('/auth/register', formData);
    if (response.success) {
      navigateTo('/login');
    } else {
      displayApiError(response.message);
    }
  } catch (error) {
    handleGenericError(error);
  }
}

This proposed implementation section serves multiple purposes: it forces the developer to think critically before coding, it provides transparency to the team about the intended solution, and it helps identify potential challenges or alternative approaches early on. It's a vital step in ensuring that the implementation aligns with the task's goals and the project's technical standards.

Definition of Done (DoD) / Completion Criteria

Clearly defining what constitutes a "completed" task is essential for ensuring quality and consistency across the project. The "Definition of Done" (DoD) provides a checklist of requirements that must be met before a sub-task can be considered finished and closed. This minimizes ambiguity and ensures that all necessary steps for delivering a piece of work have been taken.

For any technical sub-task, the following criteria should ideally be met:

• [ ] The code is implemented and functions correctly: This is the most fundamental criterion. The actual code required to fulfill the sub-task's description must be written, and it must work as intended according to the requirements. For "Maquetar registro," this means the form looks correct, is usable, and perhaps has basic styling applied.
• [ ] Tests are written and pass: For any non-trivial piece of code, comprehensive tests are crucial. This includes unit tests for individual functions or components, integration tests to verify interactions between different parts of the system, and potentially end-to-end tests to simulate user flows. All tests relevant to the implemented code must be written and passing in the development environment.
• [ ] The code follows project conventions: Adherence to established coding standards, style guides, and best practices is vital for maintainability and collaboration. This includes aspects like naming conventions, code formatting, error handling patterns, and architectural guidelines. The code should feel consistent with the rest of the codebase.
• [ ] Documentation is updated if necessary: If the task involved changes that impact how other developers or users interact with the system, or if it involved creating new features or APIs, then relevant documentation must be updated. This could include updating README files, API documentation (e.g., Swagger/OpenAPI specs), or internal wikis.
• [ ] Code has been reviewed (self-review included): Before a task is considered truly done, the code should undergo a review process. This typically starts with a self-review by the developer who implemented the task, followed by a peer review by another team member. This process helps catch errors, suggest improvements, and share knowledge.

These criteria ensure that a task isn't just "done" in a superficial sense but is delivered with quality, reliability, and maintainability in mind. It's a commitment to delivering production-ready code. For tasks that are purely documentation or investigation, some of these criteria might be adapted (e.g., "documentation is created and published" instead of "code is implemented"), but the principle of having clear, objective measures of completion remains the same. This robust DoD ensures that the team consistently delivers high-quality work.

Technical Dependencies

In any software development project, tasks rarely exist in isolation. They often depend on the completion of other tasks or block the progress of subsequent ones. Clearly identifying these technical dependencies is critical for effective project planning, scheduling, and preventing bottlenecks. This section allows you to specify these relationships explicitly.

• Depends on: #issue-number (must be completed before): Use this field to list any other tasks (User Stories, Features, or other Sub-tasks) that must be completed before this current sub-task can begin or be completed. For example, if our "Maquetar registro" (Layout registration) sub-task requires the basic Input and Button UI components to be finalized, you would list that task here: "Depends on: #123 - Create shared UI components." This ensures that work proceeds in the correct order and that developers aren't blocked waiting for prerequisites.
• Blocks: #issue-number (this task must be completed before): Conversely, this field is used to indicate tasks that cannot proceed until this current sub-task is finished. If, for instance, the "Conectar registro con API" (Connect registration to API) sub-task (let's say #456) cannot start until the "Maquetar registro" form layout (#123) is complete, you would list it here: "Blocks: #456 - Connect registration to API." This highlights critical path dependencies and helps in managing the project timeline.

These dependencies can involve internal tasks within the same project or even external factors like the availability of an external API or a third-party service. Being explicit about these relationships is crucial. It allows project managers and team leads to visualize the project's flow, identify potential risks, and make informed decisions about task prioritization. For example, if a task is both blocking multiple other tasks and dependent on a task that is already delayed, it immediately becomes a high-priority item to address.

When defining dependencies, be as specific as possible, referencing the issue numbers directly within your project management system (like Jira, GitHub Issues, etc.). This creates a clear, traceable link between related tasks. Properly managing dependencies ensures that the development process is smooth, efficient, and that the team is always working on the most critical and actionable items, minimizing delays and maximizing productivity. It's a cornerstone of agile project management.

Implementation Notes

This section is a space for additional context, considerations, or specific technical details that might be relevant for the developer implementing the task, or for anyone who might need to understand the nuances of the implementation later on. Think of it as a place to add those extra bits of information that don't fit neatly into the description or proposed implementation but are important nonetheless.

For our "Maquetar registro" (Layout registration) sub-task, implementation notes might include:

• Accessibility: "Ensure all form elements have appropriate ARIA labels and are navigable using the keyboard. Follow WCAG 2.1 AA guidelines."
• Styling Libraries: "Use Tailwind CSS for utility classes, but leverage the common-button and common-input components for consistent styling and functionality."
• Error Handling Strategy: "Client-side validation errors should appear immediately after the user attempts to submit the form or loses focus from an invalid field. Do not rely solely on backend validation for immediate user feedback."
• Performance Considerations: "Optimize image assets for the registration page if any are included. Lazy load components if the page becomes too heavy."

For a backend task, notes might cover:

• Security Best Practices: "Use parameterized queries to prevent SQL injection. Ensure password hashing uses a strong, modern algorithm like Argon2 or bcrypt with a sufficient salt round."
• Logging: "Implement detailed logging for registration attempts, including successful registrations and any errors encountered. Log to the central logging system."
• API Versioning: "This new endpoint should be part of API version 1 (/api/v1/...). Ensure future versioning strategies are considered."
• Third-Party Integrations: "If integrating with an external service (e.g., email verification), ensure the integration is resilient and includes appropriate error handling and retry mechanisms."

These notes help guide the developer toward making informed decisions during implementation, potentially saving time and preventing common pitfalls. They can also capture specific design decisions or trade-offs that were made, which is invaluable for future maintenance and debugging. It's a way to embed specific project knowledge directly into the task itself, making the work more robust and the codebase easier to understand and manage over time. By including relevant notes, you ensure that the implementation is not just functional but also aligns with the project's broader quality, security, and maintainability goals.

Checklist

Before a sub-task can be considered truly ready for review or completion, it's good practice to run through a final quick checklist. This ensures that all the preliminary steps have been taken and that the task is well-defined and appropriately set up within the project management system. It acts as a final sanity check to ensure clarity and readiness.

• [ ] The sub-task is clearly defined: Review the description, scope, and expected outcome. Is it unambiguous? Could someone else pick this up and understand exactly what needs to be done?
• [ ] The parent User Story/Feature has been identified (if applicable): If this is a sub-task of a larger story, ensure the link is correctly established. This provides the necessary context.
• [ ] Technical dependencies have been identified: Have you clearly stated what tasks need to be completed before this one can start, and what tasks this one blocks?
• [ ] The estimation is realistic (< 1 day ideally): Sub-tasks are ideally small, focused pieces of work that can be completed within a single day. If a task is estimated to take longer, consider breaking it down further. This helps maintain velocity and provides clearer progress indicators.
• [ ] This is not a bug or refactor: Double-check that this task doesn't fall into the categories of bug fixing or code refactoring. Those should be managed under their respective issue types and not as sub-tasks of a User Story.

This checklist serves as a final gate before diving deep into the implementation or before submitting the task for review. Completing these checks ensures that the task is well-scoped, properly linked, and manageable. It promotes a disciplined approach to task management, contributing to a smoother development process and more predictable outcomes. It’s a simple yet powerful tool for ensuring that every piece of work starts on the right foot.

---

For more insights into structuring technical tasks and improving development workflows, you can refer to best practices on platforms like Agile Alliance and Atlassian's Agile Coach.