Skip to content

Commit ef2bc08

Browse files
jabrenajabrena
authored
Feature/docs adr (#326)
* Adding initial ADR progres * Tested the new ADR support
1 parent 57353ce commit ef2bc08

6 files changed

Lines changed: 735 additions & 20 deletions

File tree

‎.cursor/rules/170-java-documentation.md‎

Lines changed: 294 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
author: Juan Antonio Breña Moral
33
version: 0.11.0-SNAPSHOT
44
---
5-
# Java Documentation Generator with modular step-based configuration
5+
# Java Documentation and ADR Generator with modular step-based configuration
66

77
## Role
88

@@ -11,7 +11,7 @@ You are a Senior software engineer with extensive experience in Java software de
1111
## Goal
1212

1313
This rule provides a modular, step-based approach to generating comprehensive Java project documentation
14-
including README.md files, package-info.java files, and Javadoc.
14+
including README.md files, package-info.java files, Javadoc, and Architecture Decision Records (ADRs).
1515
Each step has a single responsibility and clear dependencies on user answers, making the documentation process more maintainable and user-friendly.
1616

1717
## Constraints
@@ -48,6 +48,7 @@ Options:
4848
- README.md (project overview and usage instructions)
4949
- package-info.java files (package-level documentation)
5050
- Javadoc enhancement (improve existing Javadoc comments)
51+
- ADR (Architecture Decision Record) - interactive generation
5152
- All options: README.md, package-info.java & Javadoc files
5253
- Skip
5354

@@ -134,6 +135,18 @@ Options:
134135
- No, skip Javadoc site generation
135136

136137
---
138+
139+
**Question 10**: For ADR generation, where would you like to store the ADR files?
140+
Ask this question only if you selected "ADR (Architecture Decision Record) - interactive generation" in Question 1.
141+
142+
Options:
143+
- documentation/adr/ (recommended standard location)
144+
- docs/adr/ (alternative standard location)
145+
- adr/ (root level directory)
146+
- Custom path (I'll specify the location)
147+
148+
---
149+
137150
```
138151

139152
#### Step Constraints
@@ -582,7 +595,7 @@ After generating package-info.java files:
582595
```java
583596
/**
584597
* [Brief description of class/method purpose].
585-
*
598+
*
586599
* @param paramName [parameter description]
587600
* @return [return value description]
588601
* @throws ExceptionType [exception description]
@@ -593,14 +606,14 @@ After generating package-info.java files:
593606
```java
594607
/**
595608
* [Comprehensive description of class/method purpose and behavior].
596-
*
609+
*
597610
* <p>[Additional context about usage patterns, side effects, or important considerations]
598-
*
611+
*
599612
* <h3>Usage Example:</h3>
600613
* <pre>{@code
601614
* // Example code showing typical usage
602615
* }</pre>
603-
*
616+
*
604617
* @param paramName [detailed parameter description with constraints and expectations]
605618
* @return [detailed return value description with possible values and meanings]
606619
* @throws ExceptionType [detailed exception description with conditions that trigger it]
@@ -667,11 +680,277 @@ After enhancing Javadoc:
667680
- **MUST** validate Javadoc generation with `./mvnw javadoc:javadoc`
668681
- **MUST NOT** use generic or templated descriptions
669682

670-
### Step 5: Documentation Validation and Summary
683+
### Step 6: ADR Interactive Generation
684+
685+
**Purpose**: Generate Architecture Decision Records (ADRs) through an interactive conversational process that gathers all necessary information systematically.
686+
687+
**Dependencies**: Only execute if user selected ADR generation in Step 1. Requires completion of Step 1.
688+
689+
**CONDITIONAL EXECUTION**: Only execute this step if user selected "ADR (Architecture Decision Record) - interactive generation" in Step 1.
690+
691+
## Implementation Strategy
692+
693+
This step implements a conversational approach to create comprehensive ADRs by systematically gathering information through targeted questions, following the pattern from the referenced conversational assistant.
694+
695+
## Phase 0: Get Current Date
696+
697+
**IMPORTANT**: Before starting the ADR creation process, get the current date from the computer using the terminal command `date` to ensure accurate timestamps in the ADR document.
698+
699+
```bash
700+
date
701+
```
702+
703+
## Phase 1: Information Gathering
704+
705+
Acknowledge the request and inform the user that you need to ask some targeted questions to create a well-structured ADR. Then, systematically gather information through the conversational process outlined below.
706+
707+
**CRITICAL**: Ask questions ONE BY ONE in the exact order specified. WAIT for user response to each question before proceeding to the next.
708+
709+
### Initial Context Questions
710+
711+
1. **"What architectural decision or problem are we addressing today?"**
712+
- This helps establish the main topic and scope
713+
- Use the answer to create the ADR title
714+
715+
2. **"Can you briefly describe the current situation or context that led to this decision?"**
716+
- This fills the Context and Problem Statement section
717+
- Ask follow-up questions if the context isn't clear
718+
719+
### Stakeholder Information Questions
720+
721+
3. **"Who are the key decision-makers involved in this decision?"**
722+
- List names/roles for the decision-makers metadata field
723+
724+
4. **"Are there any subject-matter experts or stakeholders we should consult?"**
725+
- Fill the "consulted" metadata field
726+
- Distinguish between consulted (two-way communication) and informed (one-way)
727+
728+
5. **"Who else needs to be kept informed about this decision?"**
729+
- Fill the "informed" metadata field
730+
731+
### Decision Analysis Questions
732+
733+
6. **"What are the main factors driving this decision?"**
734+
- Examples: performance requirements, cost constraints, compliance needs, technical debt
735+
- This creates the Decision Drivers section
736+
737+
7. **"What options have you considered to solve this problem?"**
738+
- List all alternatives, including the "do nothing" option if relevant
739+
- For each option, ask: "Can you briefly describe this option?"
740+
741+
8. **"For each option, what are the main advantages and disadvantages?"**
742+
- This fills the Pros and Cons section
743+
- Ask specific follow-up questions about trade-offs
744+
745+
### Decision Outcome Questions
746+
747+
9. **"Which option have you chosen or do you recommend?"**
748+
- This becomes the chosen option in Decision Outcome
749+
750+
10. **"What's the main reasoning behind this choice?"**
751+
- Include criteria that ruled out other options
752+
- Mention any knockout factors
753+
754+
### Implementation and Consequences Questions
755+
756+
11. **"What positive outcomes do you expect from this decision?"**
757+
- Fill the "Good, because..." items in Consequences
758+
759+
12. **"What potential negative impacts or risks should we be aware of?"**
760+
- Fill the "Bad, because..." items in Consequences
761+
762+
13. **"How will you measure or confirm that this decision is working as intended?"**
763+
- This creates the Confirmation section
764+
- Ask about metrics, reviews, tests, or other validation methods
765+
766+
### Additional Information Questions
767+
768+
14. **"Is there any additional context, evidence, or related decisions we should document?"**
769+
- Fill the More Information section
770+
- Ask about related ADRs, external resources, or future considerations
771+
772+
15. **"What's the current status of this decision? (proposed/accepted/implemented/etc.)"**
773+
- Set the status metadata field
774+
775+
## Phase 2: ADR Document Generation
776+
777+
Once all information is gathered through conversation, inform the user you will now generate the ADR document. Use the current date obtained from the `date` command to replace the `{YYYY-MM-DD when the decision was last updated}` placeholders in the template.
778+
779+
**Template Usage**: Use the following ADR template structure:
780+
781+
```markdown
782+
---
783+
# These are optional metadata elements. Feel free to remove any of them.
784+
status: "{proposed | rejected | accepted | deprecated | … | superseded by ADR-0123}"
785+
date: {YYYY-MM-DD when the decision was last updated}
786+
decision-makers: {list everyone involved in the decision}
787+
consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
788+
informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
789+
---
790+
791+
# {short title, representative of solved problem and found solution}
792+
793+
## Context and Problem Statement
794+
795+
{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
796+
797+
<!-- This is an optional element. Feel free to remove. -->
798+
799+
## Decision Drivers
800+
801+
* {decision driver 1, e.g., a force, facing concern, …}
802+
* {decision driver 2, e.g., a force, facing concern, …}
803+
* … <!-- numbers of drivers can vary -->
804+
805+
## Considered Options
806+
807+
* {title of option 1}
808+
* {title of option 2}
809+
* {title of option 3}
810+
* … <!-- numbers of options can vary -->
811+
812+
## Decision Outcome
813+
814+
Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
815+
816+
<!-- This is an optional element. Feel free to remove. -->
817+
818+
### Consequences
819+
820+
* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
821+
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
822+
* … <!-- numbers of consequences can vary -->
823+
824+
<!-- This is an optional element. Feel free to remove. -->
825+
826+
### Confirmation
827+
828+
{Describe how the implementation / compliance of the ADR can/will be confirmed. Is there any automated or manual fitness function? If so, list it and explain how it is applied. Is the chosen design and its implementation in line with the decision? E.g., a design/code review or a test with a library such as ArchUnit can help validate this. Note that although we classify this element as optional, it is included in many ADRs.}
829+
830+
<!-- This is an optional element. Feel free to remove. -->
831+
832+
## Pros and Cons of the Options
833+
834+
### {title of option 1}
835+
836+
<!-- This is an optional element. Feel free to remove. -->
837+
{example | description | pointer to more information | …}
838+
839+
* Good, because {argument a}
840+
* Good, because {argument b}
841+
<!-- use "neutral" if the given argument weights neither for good nor bad -->
842+
* Neutral, because {argument c}
843+
* Bad, because {argument d}
844+
* … <!-- numbers of pros and cons can vary -->
845+
846+
### {title of other option}
847+
848+
{example | description | pointer to more information | …}
849+
850+
* Good, because {argument a}
851+
* Good, because {argument b}
852+
* Neutral, because {argument c}
853+
* Bad, because {argument d}
854+
* …
855+
856+
<!-- This is an optional element. Feel free to remove. -->
857+
858+
## More Information
859+
860+
{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when/how this decision the decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}
861+
```
862+
863+
## Phase 3: File Creation and Storage
864+
865+
1. **Determine ADR file location** based on user selection from Step 1:
866+
- Use the directory path selected by user in Question 10
867+
- Create directory if it doesn't exist
868+
869+
2. **Generate ADR filename**:
870+
- Format: `ADR-{number}-{short-title-kebab-case}.md`
871+
- Auto-increment number based on existing ADR files in the directory
872+
- Convert title to kebab-case (lowercase with hyphens)
873+
874+
3. **Create the ADR file** with complete content using the template structure
875+
876+
4. **Validate the generated ADR**:
877+
- Ensure all sections are properly filled
878+
- Verify markdown formatting is correct
879+
- Check that all placeholders are replaced with actual content
880+
881+
## Conversation Guidelines
882+
883+
- **Ask one question at a time** to avoid overwhelming the user
884+
- **Follow up with clarifying questions** when answers are vague or incomplete
885+
- **Summarize key points** periodically to confirm understanding
886+
- **Be flexible with the order** - if information comes up naturally, capture it even if it's out of sequence
887+
- **Suggest examples** when users seem stuck on a question
888+
- **Validate completeness** before generating the final document
889+
890+
## Example Follow-up Questions
891+
892+
- "Can you elaborate on that point?"
893+
- "What specific concerns led to this requirement?"
894+
- "How does this compare to your current approach?"
895+
- "What would happen if we don't make this decision?"
896+
- "Are there any constraints or limitations we haven't discussed?"
897+
- "Who would be most affected by this change?"
898+
899+
## Quality Checks
900+
901+
Before finalizing the ADR, ensure:
902+
- [ ] The title clearly represents both the problem and solution
903+
- [ ] The context explains why this decision is needed
904+
- [ ] All considered options are documented with pros/cons
905+
- [ ] The chosen solution is clearly justified
906+
- [ ] Consequences (both positive and negative) are realistic
907+
- [ ] Confirmation methods are specific and measurable
908+
- [ ] All stakeholders are properly categorized
909+
- [ ] Current date is properly formatted and inserted
910+
- [ ] All template placeholders are replaced with actual content
911+
912+
## Next Steps and Recommendations
913+
914+
After generating the ADR document, provide these additional recommendations:
915+
916+
**Next Steps:**
917+
1. Review and validate the ADR with all stakeholders and technical teams
918+
2. Distribute the ADR to all relevant parties for awareness and feedback
919+
3. Implement the architectural decision according to the documented approach
920+
4. Set up monitoring and validation mechanisms as defined in the Confirmation section
921+
5. Schedule regular reviews to assess the decision's effectiveness
922+
923+
**Tips for ADR Management:**
924+
- Keep the ADR living document - update it as decisions evolve or new information emerges
925+
- Ensure all team members understand the decisions and their rationale
926+
- Reference the ADR during architectural discussions and design reviews
927+
- Plan regular reviews to assess if decisions are still valid as the system evolves
928+
- Link the ADR to related user stories, technical requirements, and implementation tasks
929+
930+
#### Step Constraints
931+
932+
- **MUST** only execute if ADR generation was selected in Step 1
933+
- **MUST** get current date using `date` command before starting ADR creation
934+
- **MUST** ask questions ONE BY ONE in the exact order specified
935+
- **MUST** WAIT for user response to each question before proceeding to the next
936+
- **MUST** use the ADR template from fragments/adr-template.md
937+
- **MUST** replace all template placeholders with actual content from user responses
938+
- **MUST** use current date to replace date placeholders in template
939+
- **MUST** create ADR file in location specified by user in Step 1
940+
- **MUST** auto-generate appropriate ADR filename with incremented number
941+
- **MUST** create directory structure if it doesn't exist
942+
- **MUST** validate all sections are properly filled before finalizing
943+
- **MUST** ensure markdown formatting is correct
944+
- **MUST NOT** skip questions or change their order
945+
- **MUST NOT** assume answers or provide defaults
946+
- **MUST NOT** ask all questions simultaneously
947+
- **MUST** provide next steps and ADR management recommendations
948+
949+
### Step 7: Documentation Validation and Summary
671950

672951
**Purpose**: Validate all generated documentation and provide a comprehensive summary of changes made.
673952

674-
**Dependencies**: Requires completion of applicable steps (2, 3, and/or 4 based on user selections).
953+
**Dependencies**: Requires completion of applicable steps (2, 3, 4, and/or 6 based on user selections).
675954

676955
## Validation Process
677956

@@ -692,6 +971,7 @@ After enhancing Javadoc:
692971
- Ensure all links and references are valid
693972
- Check that software descriptions accurately reflect the codebase
694973
- Validate that Javadoc in package-info.java files is syntactically correct
974+
- Verify ADR files have proper markdown formatting and complete content
695975

696976
4. **Consistency Validation**:
697977
- Ensure consistent documentation style across all generated files
@@ -706,12 +986,14 @@ After enhancing Javadoc:
706986
- **README.md files**: [List locations and actions taken]
707987
- **package-info.java files**: [List packages and actions taken]
708988
- **Javadoc enhancements**: [List classes and methods enhanced]
989+
- **ADR files**: [List ADR files created with locations]
709990
- **Backup files**: [List any backup files created]
710991

711992
### Content Generated:
712993
- **Software descriptions**: [Summary of main functionality documented]
713994
- **Package documentation**: [Count and brief overview of packages documented]
714995
- **API documentation**: [Count and types of methods/classes documented]
996+
- **Architecture decisions**: [Summary of ADRs created with decision topics]
715997
- **Additional sections**: [Any additional sections added like Getting Started, API docs, etc.]
716998

717999
### Actions Taken:
@@ -726,6 +1008,7 @@ After enhancing Javadoc:
7261008
ls -la README.md
7271009
find . -name "package-info.java" -type f
7281010
find . -name "*.java" -exec grep -l "/**" {} \;
1011+
find . -name "ADR-*.md" -type f
7291012

7301013
# To validate compilation
7311014
./mvnw clean compile
@@ -769,10 +1052,12 @@ If validation passes, documentation generation is complete and successful.
7691052
## Output Format
7701053

7711054
- Ask documentation questions one by one following the template exactly in Step 1
772-
- Execute steps 2-4 only based on user selections from Step 1
1055+
- Execute steps 2-6 only based on user selections from Step 1
7731056
- Skip entire steps if no relevant documentation types were selected
7741057
- Generate only requested documentation types based on user selections
7751058
- Follow template specifications exactly for all documentation generation
1059+
- For ADR generation: ask conversational questions one by one and wait for responses
1060+
- For ADR generation: use current date and template to create complete ADR files
7761061
- Provide clear progress feedback showing which step is being executed
7771062
- Provide comprehensive summary of all documentation generated
7781063

0 commit comments

Comments
 (0)