Understand V01

<!-- ---
!-- Timestamp: 2025-05-11 13:27:06
!-- Author: ywatanabe
!-- File: /home/ywatanabe/.claude/commands/understand.md
!-- --- -->

# Request
- Understand and remember the following programming guidelines for my projects
- Do not care about **Response Length**. When necessary, I will prompt you "continue" in the next interaction
- Do not be lazy and skip lines of code

# Programming Guidelines & Standards

## !!! IMPORTANT !!! Test-Driven Development Workflow !!! IMPORTANT !!!
The most important guideline in this document is that we adopt test-driven development workflow as follows:
1. **Start with tests**
   - We're following test-driven development 
   - Write tests before writing source code
   - Write tests based on expected input/output pairs
   - Avoid mock implementations
   - Tests should target functionality that doesn't exist yet
   - Implement `./run-tests.sh` with these options:
     ```
     -d|--debug     Enable debug output. <- DO NOT USE this unless explicitly requested
     -h|--help      Display this help message"
     -s|--single    Run a single test file"
     ```
   - Prioritize test over source
     - The quality of test is the quality of the project
   - Test code should have the expected directory structure in the language and project goals

2. **Verify test failure**
   - Run the tests to confirm they fail first
     - Our aim is now clear; all we need is to solve the failed tests
   - Not to write implementation code yet

3. **Git commit test files**
   - Review the tests for completeness to satisfy the project goals and requirements
     - Not determine the qualities of test files based on source files
       - Prioritize test code over source code
       - Thus, test code MUST BE SOLID
   - Commit the tests when satisfied

4. **Implement functionality**
   - If the above steps 1-3 completed, now you are allowed to implement source code that passes the tests
   - !!! IMPORTANT !!! NOT TO MODIFY THE TEST FILES IN THIS STEP
   - Iterate until all tests pass

5. **Verify implementation quality**
   - Use independent subagents to check if implementation overfits to tests
   - Ensure solution meets broader requirements beyond tests

6. **Summarize the current iteration by listing:**
   - What were verified
   - What are not verified yet
     - Reasons why they are not verified if not expected

7. **Commit implementation**
   - Commit the source code once satisfied

## General Programming Rules

- **Focus on code clarity and maintainability**
  - Do Not Repeat Yourself (DRY principle)
  - Use symbolic links wisely, especially for large data to keep clear organization and easy navigation
  - Prepare `./scripts/utils/<versatile_func.py>` for versatile and reusable code
  - If versatile code is applicable beyond projects, implement in the `mngs` package
  - Avoid unnecessary comments as they can be disruptive
  - Return only the updated code without comments
  - Code should be self-explanatory; variable, function, and class names are crucial
  - Comments can be distracting if the code is properly written

- **Avoid 1-letter variable names**
  - They make searching challenging
  - For example, rename variable x to xx for better readability and searchability

- **Commenting style**
  - Subjects of comments should be "this file/code/function" implicitly
  - Verbs should be in singular form (e.g., "# Computes ..." instead of "# Compute ...")

- **Documentation**
  - Always include docstrings with example usage
  - Follow language-specific docstring format standards

- **Imports and Dependencies**
  - Keep importing packages MECE (Mutually Exclusive and Collectively Exhaustive)
  - Remove unnecessary packages and add necessary ones

- **Code Structure**
  - Use modular approaches for reusability, readability, maintainability, and scalability
  - Split functions into subroutines or meaningful chunks whenever possible

- **PATH Conventions**
  - Use relative paths from the project root
  - Relative paths should start with dots, like "./relative/example.py" or "../relative/example.txt"
  - All scripts are assumed to be executed from the project root (e.g., ./scripts/example.sh)

- **Code Block Indicators**
  - Use appropriate code block indicators:
  ```python
  # Python example

# Shell example

;; Elisp example

  # Pseudo-code

Plain text
  ```
``` markdown
Markdown Contents

• String Formatting

  • Split strings into shorter lines
  • For example, with f-string concatenation with parentheses in Python:

  # Good
  error_msg = (
      f"Failed to parse JSON response: {error}\n"
      f"Prompt: {self._ai_prompt}\n"
      f"Generated command: {commands}\n"
      f"Response: {response_text}"
  )
  
  # Not Good
  error_msg = f"Failed to parse JSON response: {error}\nPrompt: {self._ai_prompt}\nGenerated command: {commands}\nResponse: {response_text}"
  

• Headers and Footers

  • Do not change headers (e.g., time stamp, file name, authors) and footers (e.g., # EOF)

• Indentation

  • Pay attention to indentation
  • Code will be copied/pasted as is

• Org Report

  • When asked, prepare report in .org file under ./reports directory
  • Also, convert to PDF

Refactoring Rules

• During development, do not change names of files, variables, functions, and so on
• Refactoring will be separately requested

Version Control Workflow

1. Start from develop branch
2. Checkout to feature branch
3. Confirm feature branch is correctly implemented in the test-driven development schema
4. Once feature branch is verified, merge it back into develop
5. Push develop to origin/develop
6. Agents are permitted to use git and gh commands
7. SSH public key is registered in GitHub account ywatanabe1989

Project Management Progress Rules

• Direction of the project is managed under ./project_management:
  • ./project_management/progress.md
    • Main pro